Pythonssl套接字对象的TLS/SSL封装

SSL 套接字¶

class ssl.SSLSocket(socket.socket)¶

SSL 套接字提供了 套接字对象 的下列方法:

• accept()

• bind()

• close()

• connect()

• detach()

• fileno()

• getpeername(), getsockname()

• getsockopt(), setsockopt()

• gettimeout(), settimeout(),

  setblocking()

• listen()

• makefile()

• recv(), recv_into()

  (but passing a non-zero flags argument is not allowed)

• send(), sendall() (with

  the same limitation)

• sendfile() (but os.sendfile will be used

  for plain-text sockets only, else send() will be used)

• shutdown()

但是，由于 SSL（和 TLS）协议在 TCP 之上具有自己的框架，因此 SSL 套接字抽象在某些方面可能与常规的 OS 层级套接字存在差异。 特别是要查看 非阻塞型套接字说明。

SSLSocket 的实例必须使用 SSLContext.wrap_socket() 方法来创建。

在 3.5 版更改: 新增了 sendfile() 方法。

在 3.5 版更改: shutdown() 不会在每次接收或发送字节数据后重置套接字超时。 现在套接字超时为关闭的最大总持续时间。

3.6 版后已移除: 直接创建 SSLSocket 实例的做法已被弃用，请使用 SSLContext.wrap_socket() 来包装套接字。

在 3.7 版更改: SSLSocket 的实例必须使用 wrap_socket() 来创建。 在较早的版本中，直接创建实例是可能的。 但这从未被记入文档或是被正式支持。

SSL 套接字还具有下列方法和属性:

SSLSocket.read(len=1024, buffer=None)¶

从 SSL 套接字读取至多 len 个字节的数据并将结果作为 bytes 实例返回。 如果指定了 buffer，则改为读取到缓冲区，并返回所读取的字节数。

如果套接字为 非阻塞型 则会引发 SSLWantReadError 或 SSLWantWriteError 且读取将阻塞。

由于在任何时候重新协商都是可能的，因此调用 read() 也可能导致写入操作。

在 3.5 版更改: 套接字超时在每次接收或发送字节数据后不会再被重置。 现在套接字超时为读取至多 len 个字节数据的最大总持续时间。

3.6 版后已移除: 请使用 recv() 来代替 read()。

SSLSocket.write(buf)¶

将 buf 写入到 SSL 套接字并返回所写入的字节数。 buf 参数必须为支持缓冲区接口的对象。

如果套接字为 非阻塞型 则会引发 SSLWantReadError 或 SSLWantWriteError 且读取将阻塞。

由于在任何时候重新协商都是可能的，因此调用 write() 也可能导致读取操作。

在 3.5 版更改: 套接字超时在每次接收或发送字节数据后不会再被重置。 现在套接字超时为写入 buf 的最大总持续时间。

3.6 版后已移除: 请使用 send() 来代替 write()。

SSLSocket.do_handshake()¶

执行 SSL 设置握手。

在 3.4 版更改: 当套接字的 context 的 check_hostname 属性为真值时此握手方法还会执行 match_hostname()。

在 3.5 版更改: 套接字超时在每次接收或发送字节数据时不会再被重置。 现在套接字超时为握手的最大总持续时间。

在 3.7 版更改: 主机名或 IP 地址会在握手期间由 OpenSSL 进行匹配。 函数 match_hostname() 将不再被使用。 在 OpenSSL 拒绝主机名和 IP 地址的情况下，握手将提前被中止并向对等方发送 TLS 警告消息。

SSLSocket.getpeercert(binary_form=False)¶

如果连接另一端的对等方没有证书，则返回 None。 如果 SSL 握手还未完成，则会引发 ValueError。

如果 binary_form 形参为 False，并且从对等方接收到了证书，此方法将返回一个 dict 实例。 如果证书未通过验证，则字典将为空。 如果证书通过验证，它将返回由多个密钥组成的字典，其中包括 subject (证书颁发给的主体) 和 issuer (颁发证书的主体)。 如果证书包含一个 Subject Alternative Name 扩展的实例 (see RFC 3280)，则字典中还将有一个 subjectAltName 键。

subject 和 issuer 字段都是包含在证书中相应字段的数据结构中给出的相对专有名称（RDN）序列的元组，每个 RDN 均为 name-value 对的序列。 这里是一个实际的示例:

{'issuer':((('countryName','IL'),),
(('organizationName','StartCom Ltd.'),),
(('organizationalUnitName',
'Secure Digital Certificate Signing'),),
(('commonName',
'StartCom Class 2 Primary Intermediate Server CA'),)),
'notAfter':'Nov 22 08:15:19 2013 GMT',
'notBefore':'Nov 21 03:09:52 2011 GMT',
'serialNumber':'95F0',
'subject':((('description','571208-SLe257oHY9fVQ07Z'),),
(('countryName','US'),),
(('stateOrProvinceName','California'),),
(('localityName','San Francisco'),),
(('organizationName','Electronic Frontier Foundation, Inc.'),),
(('commonName','*.eff.org'),),
(('emailAddress','hostmaster@eff.org'),)),
'subjectAltName':(('DNS','*.eff.org'),('DNS','eff.org')),
'version':3}

注解

要验证特定服务的证书，你可以使用 match_hostname() 函数。

如果 binary_form 形参为 True，并且提供了证书，此方法会将整个证书的 DER 编码形式作为字节序列返回，或者如果对等方未提供证书则返回 None。 对等方是否提供证书取决于 SSL 套接字的角色:

• 对于客户端 SSL 套接字，服务器将总是提供证书，无论是否需要进行验证;

• 对于服务器 SSL 套接字，客户端将仅在服务器要求时才提供证书；因此如果你使用了 CERT_NONE (而不是 CERT_OPTIONAL 或 CERT_REQUIRED) 则 getpeercert() 将返回 None。

在 3.2 版更改: 返回的字典包括额外的条目例如 issuer 和 notBefore。

在 3.4 版更改: 如果握手未完成则会引发 ValueError。 返回的字典包括额外的 X509v3 扩展条目例如 crlDistributionPoints, caIssuers 和 OCSP URI。

在 3.7.6 版更改: IPv6 地址字符串不再附带末尾换行符。

SSLSocket.cipher()¶

返回由三个值组成的元组，其中包含所使用的密码名称，定义其使用方式的 SSL 协议，以及所使用的加密比特位数。 如果尚未建立连接，则返回 None。

SSLSocket.shared_ciphers()¶

返回在握手期间由客户端共享的密码列表。 所返回列表的每个条目都是由三个值组成的元组，其中包括密码名称，定义其使用方式的 SSL 协议版本，以及密码所使用的加密比特位数。 如果尚未建立连接或套接字为客户端套接字则 shared_ciphers() 将返回 None。

3.5 新版功能.

SSLSocket.compression()¶

以字符串形式返回所使用的压缩算法，或者如果连接没有使用压缩则返回 None。

如果高层级的协议支持自己的压缩机制，你可以使用 OP_NO_COMPRESSION 来禁用 SSL 层级的压缩。

3.3 新版功能.

SSLSocket.get_channel_binding(cb_type="tls-unique")¶

为当前连接获取字节串形式的通道绑定数据。 如果尚未连接或握手尚未完成则返回 None。

cb_type 形参允许选择需要的通道绑定类型。 有效的通道绑定类型在 CHANNEL_BINDING_TYPES 列表中列出。 目前只支持由 RFC 5929 所定义的 'tls-unique' 通道绑定。 如果请求了一个不受支持的通道绑定类型则将引发 ValueError。

3.3 新版功能.

SSLSocket.selected_alpn_protocol()¶

返回在 TLS 握手期间所选择的协议。 如果 SSLContext.set_alpn_protocols() 未被调用，如果另一方不支持 ALPN，如果此套接字不支持任何客户端所用的协议，或者如果握手尚未发生，则将返回 None。

3.5 新版功能.

SSLSocket.selected_npn_protocol()¶

返回在Return the higher-level protocol that was selected during the TLS/SSL 握手期间所选择的高层级协议。 如果 SSLContext.set_npn_protocols() 未被调用，或者如果另一方不支持 NPN，或者如果握手尚未发生，则将返回 None。

3.3 新版功能.

SSLSocket.unwrap()¶

执行 SSL 关闭握手，这会从下层的套接字中移除 TLS 层，并返回下层的套接字对象。 这可被用来通过一个连接将加密操作转为非加密。 返回的套接字应当总是被用于同连接另一方的进一步通信，而不是原始的套接字。

SSLSocket.verify_client_post_handshake()¶

向一个 TLS 1.3 客户端请求握手后身份验证（PHA）。 只有在初始 TLS 握手之后且双方都启用了 PHA 的情况下才能为服务器端套接字的 TLS 1.3 连接启用 PHA，参见 SSLContext.post_handshake_auth。

此方法不会立即执行证书交换。 服务器端会在下一次写入事件期间发送 CertificateRequest 并期待客户端在下一次读取事件期间附带证书进行响应。

如果有任何前置条件未被满足（例如非 TLS 1.3，PHA 未启用），则会引发 SSLError。

注解

仅在 OpenSSL 1.1.1 且 TLS 1.3 被启用时可用。 没有 TLS 1.3 支持，此方法将引发 NotImplementedError。

3.7.1 新版功能.

SSLSocket.version()¶

以字符串形式返回由连接协商确定的实际 SSL 协议版本，或者如果未建立安全连接则返回 None。 在撰写本文档时，可能的返回值包括 "SSLv2", "SSLv3", "TLSv1", "TLSv1.1" 和 "TLSv1.2"。 最新的 OpenSSL 版本可能会定义更多的返回值。

3.5 新版功能.

SSLSocket.pending()¶

返回在连接上等待被读取的已解密字节数。

SSLSocket.context¶

此 SSL 套接字所联结的 SSLContext 对象。 如果 SSL 套接字是使用已弃用的 wrap_socket() 函数 (而非 SSLContext.wrap_socket()) 创建的，则这将是为此 SSL 套接字创建的自定义上下文对象。

3.2 新版功能.

SSLSocket.server_side¶

一个布尔值，对于服务器端套接字为 True 而对于客户端套接字则为 False。

3.2 新版功能.

SSLSocket.server_hostname¶

服务器的主机名: str 类型，对于服务器端套接字或者如果构造器中未指定主机名则为 None。

3.2 新版功能.

在 3.7 版更改: 现在该属性将始终为 ASCII 文本。 当 server_hostname 为一个国际化域名（IDN）时，该属性现在会保存为 A 标签形式 ("xn--pythn-mua.org") 而非 U 标签形式 ("pythön.org")。

SSLSocket.session¶

用于 SSL 连接的 SSLSession。 该会话将在执行 TLS 握手后对客户端和服务器端套接字可用。 对于客户端套接字该会话可以在调用 do_handshake() 之前被设置以重用一个会话。

3.6 新版功能.

SSLSocket.session_reused¶

3.6 新版功能.

SSL 上下文¶

SSL 上下文可保存各种比单独 SSL 连接寿命更长的数据，例如 SSL 配置选项，证书和私钥等。 它还可为服务器端套接字管理缓存，以加快来自相同客户端的重复连接。

class ssl.SSLContext(protocol=PROTOCOL_TLS)¶

创建一个新的 SSL 上下文。 你可以传入 protocol，它必须为此模块中定义的 PROTOCOL_* 常量之一。 该形参指定要使用哪个 SSL 协议版本。 通常，服务器会选择一个特定的协议版本，而客户端必须适应服务器的选择。 大多数版本都不能与其他版本互操作。 如果未指定，则默认值为 PROTOCOL_TLS；它提供了与其他版本的最大兼容性。

这个表显示了客户端（横向）的哪个版本能够连接服务器（纵向）的哪个版本。

client / server	SSLv2	SSLv3	TLS 3	TLSv1	TLSv1.1	TLSv1.2
SSLv2	是	否	no 1	否	否	否
SSLv3	否	是	no 2	否	否	否
TLS (SSLv23) 3	no 1	no 2	是	是	是	是
TLSv1	否	否	是	是	否	否
TLSv1.1	否	否	是	否	是	否
TLSv1.2	否	否	是	否	否	是

备注

1(1,2)

SSLContext 默认设置 OP_NO_SSLv2 以禁用 SSLv2。

2(1,2)

SSLContext 默认设置 OP_NO_SSLv3 以禁用 SSLv3。

3(1,2)

TLS 1.3 协议在 OpenSSL >= 1.1.1 中设置 PROTOCOL_TLS 时可用。 没有专门针对 TLS 1.3 的 PROTOCOL 常量。

参见

create_default_context() 让 ssl 为特定目标选择安全设置。

在 3.6 版更改: 上下文会使用安全默认值来创建。 默认设置的选项有 OP_NO_COMPRESSION, OP_CIPHER_SERVER_PREFERENCE, OP_SINGLE_DH_USE, OP_SINGLE_ECDH_USE, OP_NO_SSLv2 (except for PROTOCOL_SSLv2) 和 OP_NO_SSLv3 (except for PROTOCOL_SSLv3)。 初始密码集列表只包含 HIGH 密码，不包含 NULL 密码和 MD5 密码 (PROTOCOL_SSLv2 除外)。

SSLContext 对象具有以下方法和属性:

SSLContext.cert_store_stats()¶

获取以字典表示的有关已加载的 X.509 证书数量，被标记为 CA 证书的 X.509 证书数量以及证书吊销列表的的统计信息。

具有一个 CA 证书和一个其他证书的上下文示例:

>>> context.cert_store_stats()
{'crl': 0, 'x509_ca': 1, 'x509': 2}

3.4 新版功能.

SSLContext.load_cert_chain(certfile, keyfile=None, password=None)¶

加载一个私钥及对应的证书。 certfile 字符串必须为以 PEM 格式表示的单个文件路径，该文件中包含证书以及确立证书真实性所需的任意数量的 CA 证书。 如果存在 keyfile 字符串，它必须指向一个包含私钥的文件。 否则私钥也将从 certfile 中提取。 请参阅 证书 中的讨论来了解有关如何将证书存储至 certfile 的更多信息。

password 参数可以是一个函数，调用时将得到用于解密私钥的密码。 它在私钥被加密且需要密码时才会被调用。 它调用时将不带任何参数，并且应当返回一个字符串、字节串或字节数组。 如果返回值是一个字符串，在用它解密私钥之前它将以 UTF-8 进行编码。 或者也可以直接将字符串、字节串或字节数组值作为 password 参数提供。 如果私钥未被加密且不需要密码则它将被忽略。

如果未指定 password 参数且需要一个密码，将会使用 OpenSSL 内置的密码提示机制来交互式地提示用户输入密码。

如果私钥不能匹配证书则会引发 SSLError。

在 3.3 版更改: 新增可选参数 password。

SSLContext.load_default_certs(purpose=Purpose.SERVER_AUTH)¶

从默认位置加载一组默认的 "证书颁发机构" (CA) 证书。 在 Windows 上它将从 CA 和 ROOT 系统存储中加载 CA 证书。 在其他系统上它会调用 SSLContext.set_default_verify_paths()。 将来该方法也可能会从其他位置加载 CA 证书。

purpose 旗标指明要加载哪一类 CA 证书。 默认设置 Purpose.SERVER_AUTH 加载被标记且被信任用于 TLS Web 服务器验证（客户端套接字）的证书。 Purpose.CLIENT_AUTH 则加载用于在服务器端进行客户端证书验证的 CA 证书。

3.4 新版功能.

SSLContext.load_verify_locations(cafile=None, capath=None, cadata=None)¶

当 verify_mode 不为 CERT_NONE 时加载一组用于验证其他对等方证书的 "证书颁发机构" (CA) 证书。 必须至少指定 cafile 或 capath 中的一个。

此方法还可加载 PEM 或 DER 格式的证书吊销列表 (CRL)，为此必须正确配置 SSLContext.verify_flags。

如果存在 cafile 字符串，它应为 PEM 格式的级联 CA 证书文件的路径。 请参阅 证书 中的讨论来了解有关如何处理此文件中的证书的更多信息。

如果存在 capath 字符串，它应为包含多个 PEM 格式的 CA 证书的目录的路径，并遵循 OpenSSL 专属布局。

如果存在 cadata 对象，它应为一个或多个 PEM 编码的证书的 ASCII 字符串或者 DER 编码的证书的 bytes-like object。 与 capath 一样 PEM 编码的证书之外的多余行会被忽略，但至少要有一个证书。

在 3.4 版更改: 新增可选参数 cadata

SSLContext.get_ca_certs(binary_form=False)¶

获取已离开法人 "证书颁发机构" (CA) 证书列表。 如果 binary_form 形参为 False 则每个列表条目都是一个类似于 SSLSocket.getpeercert() 输出的字典。 在其他情况下此方法将返回一个 DER 编码的证书的列表。 返回的列表不包含来自 capath 的证书，除非 SSL 连接请求并加载了一个证书。

注解

capath 目录中的证书不会被加载，除非它们已至少被使用过一次。

3.4 新版功能.

SSLContext.get_ciphers()¶

获取已启用密码的列表。 该列表将按密码的优先级排序。 参见 SSLContext.set_ciphers()。

示例:

>>> ctx=ssl.SSLContext(ssl.PROTOCOL_SSLv23)
>>> ctx.set_ciphers('ECDHE+AESGCM:!ECDSA')
>>> ctx.get_ciphers()# OpenSSL 1.0.x
[{'alg_bits': 256,
  'description': 'ECDHE-RSA-AES256-GCM-SHA384 TLSv1.2 Kx=ECDH     Au=RSA  '
                 'Enc=AESGCM(256) Mac=AEAD',
  'id': 50380848,
  'name': 'ECDHE-RSA-AES256-GCM-SHA384',
  'protocol': 'TLSv1/SSLv3',
  'strength_bits': 256},
 {'alg_bits': 128,
  'description': 'ECDHE-RSA-AES128-GCM-SHA256 TLSv1.2 Kx=ECDH     Au=RSA  '
                 'Enc=AESGCM(128) Mac=AEAD',
  'id': 50380847,
  'name': 'ECDHE-RSA-AES128-GCM-SHA256',
  'protocol': 'TLSv1/SSLv3',
  'strength_bits': 128}]

在 OpenSSL 1.1 及更新的版本中密码字典会包含额外的字段:

>>> ctx.get_ciphers()# OpenSSL 1.1+
[{'aead': True,
  'alg_bits': 256,
  'auth': 'auth-rsa',
  'description': 'ECDHE-RSA-AES256-GCM-SHA384 TLSv1.2 Kx=ECDH     Au=RSA  '
                 'Enc=AESGCM(256) Mac=AEAD',
  'digest': None,
  'id': 50380848,
  'kea': 'kx-ecdhe',
  'name': 'ECDHE-RSA-AES256-GCM-SHA384',
  'protocol': 'TLSv1.2',
  'strength_bits': 256,
  'symmetric': 'aes-256-gcm'},
 {'aead': True,
  'alg_bits': 128,
  'auth': 'auth-rsa',
  'description': 'ECDHE-RSA-AES128-GCM-SHA256 TLSv1.2 Kx=ECDH     Au=RSA  '
                 'Enc=AESGCM(128) Mac=AEAD',
  'digest': None,
  'id': 50380847,
  'kea': 'kx-ecdhe',
  'name': 'ECDHE-RSA-AES128-GCM-SHA256',
  'protocol': 'TLSv1.2',
  'strength_bits': 128,
  'symmetric': 'aes-128-gcm'}]

可用性: OpenSSL 1.0.2+。

3.6 新版功能.

SSLContext.set_default_verify_paths()¶

从构建 OpenSSL 库时定义的文件系统路径中加载一组默认的 "证书颁发机构" (CA) 证书。 不幸的是，没有一种简单的方式能知道此方法是否执行成功：如果未找到任何证书也不会返回错误。 不过，当 OpenSSL 库是作为操作系统的一部分被提供时，它的配置应当是正确的。

SSLContext.set_ciphers(ciphers)¶

为使用此上下文创建的套接字设置可用密码。 它应当为 OpenSSL 密码列表格式 的字符串。 如果没有可被选择的密码（由于编译时选项或其他配置禁止使用所指定的任何密码），则将引发 SSLError。

注解

在连接后，SSL 套接字的 SSLSocket.cipher() 方法将给出当前所选择的密码。

在默认情况下 OpenSSL 1.1.1 会启用 TLS 1.3 密码套件。 该套件不能通过 set_ciphers() 来禁用。

SSLContext.set_alpn_protocols(protocols)¶

指定在 SSL/TLS 握手期间套接字应当通告的协议。 它应为由 ASCII 字符串组成的列表，例如 ['http/1.1','spdy/2']，按首选顺序排列。 协议的选择将在握手期间发生，并依据 RFC 7301 来执行。 在握手成功后，SSLSocket.selected_alpn_protocol() 方法将返回已达成一致的协议。

如果 HAS_ALPN 为 False 则此方法将引发 NotImplementedError。

当双方都支持 ALPN 但不能就协议达成一致时 OpenSSL 1.1.0 至 1.1.0e 将中止并引发 SSLError。 1.1.0f+ 的行为类似于 1.0.2，SSLSocket.selected_alpn_protocol() 返回 None。

3.5 新版功能.

SSLContext.set_npn_protocols(protocols)¶

指定在Specify which protocols the socket should advertise during the SSL/TLS 握手期间套接字应当通告的协议。 它应为由字符串组成的列表，例如 ['http/1.1','spdy/2']，按首选顺序排列。 协议的选择将在握手期间发生，并将依据 应用层协议协商 来执行。 在握手成功后，SSLSocket.selected_npn_protocol() 方法将返回已达成一致的协议。

如果 HAS_NPN 为 False 则此方法将引发 NotImplementedError。

3.3 新版功能.

SSLContext.sni_callback¶

注册一个回调函数，当 TLS 客户端指定了一个服务器名称提示时，该回调函数将在 SSL/TLS 服务器接收到 TLS Client Hello 握手消息后被调用。 服务器名称提示机制的定义见 RFC 6066 section 3 - Server Name Indication。

每个 SSLContext 只能设置一个回调。 如果 sni_callback 被设置为 None 则会禁用回调。 对该函数的后续调用将禁用之前注册的回调。

此回调函数将附带三个参数来调用；第一个参数是 ssl.SSLSocket，第二个参数是代表客户端准备与之通信的服务器的字符串 (或者如果 TLS Client Hello 不包含服务器名称则为 None) 而第三个参数是原来的 SSLContext。 服务器名称参数为文本形式。 对于国际化域名，服务器名称是一个 IDN A 标签 ("xn--pythn-mua.org")。

此回调的一个典型用法是将 ssl.SSLSocket 的 SSLSocket.context 属性修改为一个 SSLContext 类型的新对象，该对象代表与服务器相匹配的证书链。

由于 TLS 连接处于早期协商阶段，因此仅能使用有限的方法和属性例如 SSLSocket.selected_alpn_protocol() 和 SSLSocket.context。 SSLSocket.getpeercert(), SSLSocket.getpeercert(), SSLSocket.cipher() 和 SSLSocket.compress() 方法要求 TLS 连接已经过 TLS Client Hello 因而将既不包含返回有意义的值，也不能安全地调用它们。

sni_callback 函数必须返回 None 以允许 TLS 协商继续进行。 如果想要 TLS 失败，则可以返回常量 ALERT_DESCRIPTION_*。 其他返回值将导致 TLS 的致命错误 ALERT_DESCRIPTION_INTERNAL_ERROR.

如果从 sni_callback 函数引发了异常，则 TLS 连接将终止并发出 TLS 致命警告消息 ALERT_DESCRIPTION_HANDSHAKE_FAILURE。

如果 OpenSSL library 库在构建时定义了 OPENSSL_NO_TLSEXT 则此方法将返回 NotImplementedError。

3.7 新版功能.

SSLContext.set_servername_callback(server_name_callback)¶

这是被保留用于向下兼容的旧式 API。 在可能的情况下，你应当改用 sni_callback。 给出的 server_name_callback 类似于 sni_callback，不同之处在于当服务器主机名是 IDN 编码的国际化域名时，server_name_callback 会接收到一个已编码的 U 标签 ("pythön.org")。

如果发生了服务器名称解码错误。 TLS 连接将终止并向客户端发出 ALERT_DESCRIPTION_INTERNAL_ERROR 致命的 TLS 警告消息。

3.4 新版功能.

SSLContext.load_dh_params(dhfile)¶

加载密钥生成参数用于 Diffie-Hellman (DH) 密钥交换。 使用 DH 密钥交换能以消耗（服务器和客户端的）计算资源为代价提升前向保密性。 dhfile 参数应当为指向一个包含 PEM 格式的 DH 形参的文件的路径。

此设置不会应用于客户端套接字。 你还可以使用 OP_SINGLE_DH_USE 选项来进一步提升安全性。

3.3 新版功能.

SSLContext.set_ecdh_curve(curve_name)¶

为基于椭圆曲线的 Elliptic Curve-based Diffie-Hellman (ECDH) 密钥交换设置曲线名称。 ECDH 显著快于常规 DH 同时据信同样安全。 curve_name 形参应为描述某个知名椭圆曲线的字符串，例如受到广泛支持的曲线 prime256v1。

此设置不会应用于客户端套接字。 你还可以使用 OP_SINGLE_ECDH_USE 选项来进一步提升安全性。

如果 HAS_ECDH 为 False 则此方法将不可用。

3.3 新版功能.

参见

SSL/TLS 与完美的前向保密性

Vincent Bernat。

SSLContext.wrap_socket(sock, server_side=False, do_handshake_on_connect=True, suppress_ragged_eofs=True, server_hostname=None, session=None)¶

包装一个现有的 Python 套接字 sock 并返回一个 SSLContext.sslsocket_class 的实例 (默认为 SSLSocket)。 返回的 SSL 套接字会绑定上下文、设置以及证书。 sock 必须是一个 SOCK_STREAM 套接字；其他套接字类型不被支持。

形参 server_side 是一个布尔值，它标明希望从该套接字获得服务器端行为还是客户端行为。

对于客户端套接字，上下文的构造会延迟执行；如果下层的套接字尚未连接，上下文的构造将在对套接字调用 connect() 之后执行。 对于服务器端套接字，如果套接字没有远端对等方，它会被视为一个监听套接字，并且服务器端 SSL 包装操作会在通过 accept() 方法所接受的客户端连接上自动执行。 此方法可能会引发 SSLError。

在客户端连接上，可选形参 server_hostname 指定所要连接的服务的主机名。 这允许单个服务器托管具有单独证书的多个基于 SSL 的服务，很类似于 HTTP 虚拟主机。 如果 server_side 为真值则指定 server_hostname 将引发 ValueError。

形参 do_handshake_on_connect 指明是否要在调用 socket.connect() 之后自动执行 SSL 握手，还是要通过发起调用 SSLSocket.do_handshake() 方法让应用程序显式地调用它。 显式地调用 SSLSocket.do_handshake() 可给予程序对握手中所涉及的套接字 I/O 阻塞行为的控制。

形参 suppress_ragged_eofs 指明 SSLSocket.recv() 方法应当如何从连接的另一端发送非预期的 EOF 信号。 如果指定为 True (默认值)，它将返回正常的 EOF (空字节串对象) 来响应从下层套接字引发的非预期的 EOF 错误；如果指定为 False，它将向调用方引发异常。

session，参见 session。

在 3.5 版更改: 总是允许传送 server_hostname，即使 OpenSSL 没有 SNI。

在 3.6 版更改: 增加了 session 参数。

在 3.7 版更改: 此方法返回 SSLContext.sslsocket_class 的实例而非硬编码的 SSLSocket。

SSLContext.sslsocket_class¶

SSLContext.wrap_socket() 的返回类型，默认为 SSLSocket。 该属性可以在类实例上被重载以便返回自定义的 SSLSocket 的子类。

3.7 新版功能.

SSLContext.wrap_bio(incoming, outgoing, server_side=False, server_hostname=None, session=None)¶

包装 BIO 对象 incoming 和 outgoing 并返回一个 SSLContext.sslobject_class (默认为 SSLObject) 的实例。 SSL 例程将从 BIO 中读取输入数据并将数据写入到 outgoing BIO。

server_side, server_hostname 和 session 形参具有与 SSLContext.wrap_socket() 中相同的含义。

在 3.6 版更改: 增加了 session 参数。

在 3.7 版更改: 此方法返回 SSLContext.sslobject_class 的实例则非硬编码的 SSLObject。

SSLContext.sslobject_class¶

SSLContext.wrap_bio() 的返回类型，默认为 SSLObject。 该属性可以在类实例上被重载以便返回自定义的 SSLObject 的子类。

3.7 新版功能.

SSLContext.session_stats()¶

获取由此上下文所创建或管理的 SSL 会话的相关统计信息。 返回将每个 信息片 的名称映射到其数字值的字典。 例如，以下是自上下文被创建以来会话缓存中命中和未命中的总数:

>>> stats=context.session_stats()
>>> stats['hits'],stats['misses']
(0, 0)

SSLContext.check_hostname¶

是否要将对等方证书的主机名与 SSLSocket.do_handshake() 中的 match_hostname() 进行匹配。 上下文的 verify_mode 必须被设为 CERT_OPTIONAL 或 CERT_REQUIRED，并且你必须将 server_hostname 传给 wrap_socket() 以便匹配主机名。 启用主机名检查会自动将 sets verify_mode 从 CERT_NONE 设置为 CERT_REQUIRED。 只要启用了主机名检查就不能将其设置回 CERT_NONE。 PROTOCOL_TLS_CLIENT 协议默认启用主机名检查。 对于其他协议，则必须显式地启用主机名检查。

示例:

importsocket,ssl
context=ssl.SSLContext(ssl.PROTOCOL_TLSv1_2)
context.verify_mode=ssl.CERT_REQUIRED
context.check_hostname=True
context.load_default_certs()
s=socket.socket(socket.AF_INET,socket.SOCK_STREAM)
ssl_sock=context.wrap_socket(s,server_hostname='www.verisign.com')
ssl_sock.connect(('www.verisign.com',443))

3.4 新版功能.

在 3.7 版更改: 现在当主机名检查被启用且 verify_mode 为 CERT_NONE 时 verify_mode 会自动更改为 CERT_REQUIRED。 在之前版本中同样的操作将失败并引发 ValueError。

注解

此特性要求 OpenSSL 0.9.8f 或更新的版本。

SSLContext.maximum_version¶

一个代表所支持的最高 TLS 版本的 TLSVersion 枚举成员。 该值默认为 TLSVersion.MAXIMUM_SUPPORTED。 这个属性对于 PROTOCOL_TLS, PROTOCOL_TLS_CLIENT 和 PROTOCOL_TLS_SERVER 以外的其他协议来说都是只读的。

maximum_version, minimum_version 和 SSLContext.options 等属性都会影响上下文所支持的 SSL 和 TLS 版本。 这个实现不会阻止无效的组合。 例如一个 options 为 OP_NO_TLSv1_2 而 maximum_version 设为 TLSVersion.TLSv1_2 的上下文将无法建立 TLS 1.2 连接。

注解

除非 ssl 模块使用 OpenSSL 1.1.0g 或更新的版本编译否则这个属性将不可用。

3.7 新版功能.

SSLContext.minimum_version¶

与 SSLContext.maximum_version 类似，区别在于它是所支持的最低版本或为 TLSVersion.MINIMUM_SUPPORTED。

注解

除非 ssl 模块使用 OpenSSL 1.1.0g 或更新的版本编译否则这个属性将不可用。

3.7 新版功能.

SSLContext.options¶

一个代表此上下文中所启用的 SSL 选项集的整数。 默认值为 OP_ALL，但你也可以通过在选项间进行 OR 运算来指定其他选项例如 OP_NO_SSLv2。

注解

对于 0.9.8m 之前的 OpenSSL 版本，只能设置选项，而不能清除它们。 尝试（通过重置相应比特位）清除选项将会引发 ValueError。

在 3.6 版更改: SSLContext.options 返回 Options 旗标:

>>> ssl.create_default_context().options
<Options.OP_ALL|OP_NO_SSLv3|OP_NO_SSLv2|OP_NO_COMPRESSION: 2197947391>

SSLContext.post_handshake_auth¶

启用 TLS 1.3 握手后客户端身份验证。 握手后验证默认是被禁用的，服务器只能在初始握手期间请求 TLS 客户端证书。 当启用时，服务器可以在握手之后的任何时候请求 TLS 客户端证书。

当在客户端套接字上启用时，客户端会向服务器发信号说明它支持握手后身份验证。

当在服务器端套接字上启用时，SSLContext.verify_mode 也必须被设为 CERT_OPTIONAL 或 CERT_REQUIRED。 实际的客户端证书交换会被延迟直至 SSLSocket.verify_client_post_handshake() 被调用并执行了一些 I/O 操作后再进行。

注解

仅在 OpenSSL 1.1.1 且 TLS 1.3 被启用时可用。 如果没有 TLS 1.3 支持，该属性值将为 None 且不可被更改

3.7.1 新版功能.

SSLContext.protocol¶

构造上下文时所选择的协议版本。 这个属性是只读的。

SSLContext.hostname_checks_common_name¶

在没有目标替代名称扩展的情况下 check_hostname 是否要回退为验证证书的通用名称（默认为真值）。

注解

仅在 OpenSSL 1.1.0 或更新的版本上可写。

3.7 新版功能.

SSLContext.verify_flags¶

证书验证操作的旗标。 你可以通过对 VERIFY_CRL_CHECK_LEAF 等值执行 OR 运算来设置组合旗标。 在默认情况下 OpenSSL 不会要求也不会验证证书吊销列表（CRL）。 仅在 openssl 版本 0.9.8+ 上可用。

3.4 新版功能.

在 3.6 版更改: SSLContext.verify_flags 返回 VerifyFlags 旗标:

>>> ssl.create_default_context().verify_flags
<VerifyFlags.VERIFY_X509_TRUSTED_FIRST: 32768>

SSLContext.verify_mode¶

是否要尝试验证其他对等方的证书以及如果验证失败应采取何种行为。 该属性值必须为 CERT_NONE, CERT_OPTIONAL 或 CERT_REQUIRED 之一。

在 3.6 版更改: SSLContext.verify_mode 返回 VerifyMode 枚举:

>>> ssl.create_default_context().verify_mode
<VerifyMode.CERT_REQUIRED: 2>

证书¶

总的来说证书是公钥/私钥系统的一个组成部分。 在这个系统中，每 个 主体 (可能是一台机器、一个人或者一个组织) 都会分配到唯一的包含两部分的加密密钥。 一部分密钥是公开的，称为 公钥；另一部分密钥是保密的，称为 私钥。 这两个部分是互相关联的，就是说如果你用其中一个部分来加密一条消息，你将能用并且 只能 用另一个部分来解密它。

在一个证书中包含有两个主体的相关信息。 它包含 目标方 的名称和目标方的公钥。 它还包含由第二个主体 颁发方 所发布的声明：目标方的身份与他们所宣称的一致，包含的公钥也确实是目标方的公钥。 颁发方的声明使用颁发方的私钥进行签名，该私钥的内容只有颁发方自己才知道。 但是，任何人都可以找到颁发方的公钥，用它来解密这个声明，并将其与证书中的其他信息进行比较来验证颁发方声明的真实性。 证书还包含有关其有效期限的信息。 这被表示为两个字段，即 "notBefore" 和 "notAfter"。

在 Python 中应用证书时，客户端或服务器可以用证书来证明自己的身份。 还可以要求网络连接的另一方提供证书，提供的证书可以用于验证以满足客户端或服务器的验证要求。 如果验证失败，连接尝试可被设置为引发一个异常。 验证是由下层的 OpenSSL 框架来自动执行的；应用程序本身不必关注其内部的机制。 但是应用程序通常需要提供一组证书以允许此过程的发生。

Python 使用文件来包含证书。 它们应当采用 "PEM" 格式 (参见 RFC 1422)，这是一种带有头部行和尾部行的 base-64 编码包装形式:

-----BEGINCERTIFICATE-----
...(certificateinbase64PEMencoding)...
-----ENDCERTIFICATE-----

-----BEGINCERTIFICATE-----
...(certificateforyourserver)...
-----ENDCERTIFICATE-----
-----BEGINCERTIFICATE-----
...(thecertificatefortheCA)...
-----ENDCERTIFICATE-----
-----BEGINCERTIFICATE-----
...(therootcertificatefortheCA's issuer)...
-----ENDCERTIFICATE-----

-----BEGINRSAPRIVATEKEY-----
...(privatekeyinbase64encoding)...
-----ENDRSAPRIVATEKEY-----
-----BEGINCERTIFICATE-----
...(certificateinbase64PEMencoding)...
-----ENDCERTIFICATE-----

%opensslreq-new-x509-days365-nodes-outcert.pem-keyoutcert.pem
Generatinga1024bitRSAprivatekey
.......++++++
.............................++++++
writingnewprivatekeyto'cert.pem'
-----
Youareabouttobeaskedtoenterinformationthatwillbeincorporated
intoyourcertificaterequest.
WhatyouareabouttoenteriswhatiscalledaDistinguishedNameoraDN.
Therearequiteafewfieldsbutyoucanleavesomeblank
Forsomefieldstherewillbeadefaultvalue,
Ifyouenter'.',thefieldwillbeleftblank.
-----
CountryName(2lettercode)[AU]:US
StateorProvinceName(fullname)[Some-State]:MyState
LocalityName(eg,city)[]:SomeCity
OrganizationName(eg,company)[InternetWidgitsPtyLtd]:MyOrganization,Inc.
OrganizationalUnitName(eg,section)[]:MyGroup
CommonName(eg,YOURname)[]:myserver.mygroup.myorganization.com
EmailAddress[]:ops@myserver.mygroup.myorganization.com
%

try:
importssl
exceptImportError:
pass
else:
...# do something that requires SSL support

>>> context=ssl.create_default_context()

>>> context=ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
>>> context.load_verify_locations("/etc/ssl/certs/ca-bundle.crt")

>>> conn=context.wrap_socket(socket.socket(socket.AF_INET),
... server_hostname="www.python.org")
>>> conn.connect(("www.python.org",443))

>>> cert=conn.getpeercert()

>>> pprint.pprint(cert)
{'OCSP': ('http://ocsp.digicert.com',),
 'caIssuers': ('http://cacerts.digicert.com/DigiCertSHA2ExtendedValidationServerCA.crt',),
 'crlDistributionPoints': ('http://crl3.digicert.com/sha2-ev-server-g1.crl',
                           'http://crl4.digicert.com/sha2-ev-server-g1.crl'),
 'issuer': ((('countryName', 'US'),),
            (('organizationName', 'DigiCert Inc'),),
            (('organizationalUnitName', 'www.digicert.com'),),
            (('commonName', 'DigiCert SHA2 Extended Validation Server CA'),)),
 'notAfter': 'Sep  9 12:00:00 2016 GMT',
 'notBefore': 'Sep  5 00:00:00 2014 GMT',
 'serialNumber': '01BB6F00122B177F36CAB49CEA8B6B26',
 'subject': ((('businessCategory', 'Private Organization'),),
             (('1.3.6.1.4.1.311.60.2.1.3', 'US'),),
             (('1.3.6.1.4.1.311.60.2.1.2', 'Delaware'),),
             (('serialNumber', '3359300'),),
             (('streetAddress', '16 Allen Rd'),),
             (('postalCode', '03894-4801'),),
             (('countryName', 'US'),),
             (('stateOrProvinceName', 'NH'),),
             (('localityName', 'Wolfeboro'),),
             (('organizationName', 'Python Software Foundation'),),
             (('commonName', 'www.python.org'),)),
 'subjectAltName': (('DNS', 'www.python.org'),
                    ('DNS', 'python.org'),
                    ('DNS', 'pypi.org'),
                    ('DNS', 'docs.python.org'),
                    ('DNS', 'testpypi.org'),
                    ('DNS', 'bugs.python.org'),
                    ('DNS', 'wiki.python.org'),
                    ('DNS', 'hg.python.org'),
                    ('DNS', 'mail.python.org'),
                    ('DNS', 'packaging.python.org'),
                    ('DNS', 'pythonhosted.org'),
                    ('DNS', 'www.pythonhosted.org'),
                    ('DNS', 'test.pythonhosted.org'),
                    ('DNS', 'us.pycon.org'),
                    ('DNS', 'id.python.org')),
 'version': 3}

>>> conn.sendall(b"HEAD / HTTP/1.0\r\nHost: linuxfr.org\r\n\r\n")
>>> pprint.pprint(conn.recv(1024).split(b"\r\n"))
[b'HTTP/1.1 200 OK',
 b'Date: Sat, 18 Oct 2014 18:27:20 GMT',
 b'Server: nginx',
 b'Content-Type: text/html; charset=utf-8',
 b'X-Frame-Options: SAMEORIGIN',
 b'Content-Length: 45679',
 b'Accept-Ranges: bytes',
 b'Via: 1.1 varnish',
 b'Age: 2188',
 b'X-Served-By: cache-lcy1134-LCY',
 b'X-Cache: HIT',
 b'X-Cache-Hits: 11',
 b'Vary: Cookie',
 b'Strict-Transport-Security: max-age=63072000; includeSubDomains',
 b'Connection: close',
 b'',
 b'']

importsocket,ssl
context=ssl.create_default_context(ssl.Purpose.CLIENT_AUTH)
context.load_cert_chain(certfile="mycertfile",keyfile="mykeyfile")
bindsocket=socket.socket()
bindsocket.bind(('myaddr.mydomain.com',10023))
bindsocket.listen(5)

whileTrue:
newsocket,fromaddr=bindsocket.accept()
connstream=context.wrap_socket(newsocket,server_side=True)
try:
deal_with_client(connstream)
finally:
connstream.shutdown(socket.SHUT_RDWR)
connstream.close()

defdeal_with_client(connstream):
data=connstream.recv(1024)
# empty data means the client is finished with us
whiledata:
ifnotdo_something(connstream,data):
# we'll assume do_something returns False
# when we're finished with client
break
data=connstream.recv(1024)
# finished with client