注意

某些行为可能与平台有关，因为对操作系统套接字API进行了调用。安装的OpenSSL版本也可能导致行为的变化。例如，TL​​Sv1.1和TLSv1.2附带openssl版本1.0.1。

警告

如果不阅读安全注意事项，请勿使用此模块。这样做可能会导致错误的安全感，因为ssl模块的默认设置不一定适合您的应用程序。

版本3.5.3中已更改：已更新以支持与OpenSSL 1.1.0的链接

版本3.6中已更改：不推荐使用OpenSSL 0.9.8,1.0.0和1.0.1，不再支持。将来，ssl模块至少需要OpenSSL 1.0.2或1.1.0。

函数，常量和异常

import socket
import sslhostname = 'www.python.org'
context = ssl.create_default_context()with socket.create_connection((hostname, 443)) as sock:with context.wrap_socket(sock, server_hostname=hostname) as ssock:print(ssock.version())

hostname = 'www.python.org'
# PROTOCOL_TLS_CLIENT requires valid cert chain and hostname
context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
context.load_verify_locations('path/to/cabundle.pem')with socket.socket(socket.AF_INET, socket.SOCK_STREAM, 0) as sock:with context.wrap_socket(sock, server_hostname=hostname) as ssock:print(ssock.version())

context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
context.load_cert_chain('/path/to/certchain.pem', '/path/to/private.key')with socket.socket(socket.AF_INET, socket.SOCK_STREAM, 0) as sock:sock.bind(('127.0.0.1', 8443))sock.listen(5)with context.wrap_socket(sock, server_side=True) as ssock:conn, addr = ssock.accept()...

ctx = ssl.create_default_context(Purpose.CLIENT_AUTH) ctx.options &= ~ssl.OP_NO_SSLv3 

>>> cert = {'subject': ((('commonName', 'example.com'),),)}
>>> ssl.match_hostname(cert, "example.com")
>>> ssl.match_hostname(cert, "example.org")
Traceback (most recent call last):File "<stdin>", line 1, in <module>File "/home/py3k/Lib/ssl.py", line 130, in match_hostname
ssl.CertificateError: hostname 'example.org' doesn't match 'example.com'

>>> import ssl
>>> timestamp = ssl.cert_time_to_seconds("Jan 5 09:34:43 2018 GMT")
>>> timestamp
1515144883
>>> from datetime import datetime
>>> print(datetime.utcfromtimestamp(timestamp))
2018-01-05 09:34:43

>>> ssl.enum_certificates("CA")
[(b'data...', 'x509_asn', {'1.3.6.1.5.5.7.3.1', '1.3.6.1.5.5.7.3.2'}),
 (b'data...', 'x509_asn', True)]

>>> ssl.OPENSSL_VERSION
'OpenSSL 1.0.2k 26 Jan 2017'

>>> ssl.OPENSSL_VERSION_INFO
(1, 0, 2, 11, 15)

>>> ssl.OPENSSL_VERSION_NUMBER
268443839
>>> hex(ssl.OPENSSL_VERSION_NUMBER)
'0x100020bf'

SSL套接字

class ssl.SSLSocket（socket.socket ）

SSL套接字提供以下Socket对象方法：

• accept()
• bind()
• close()
• connect()
• detach()
• fileno()
• getpeername()， getsockname()
• getsockopt()， setsockopt()
• gettimeout()，settimeout()， setblocking()
• listen()
• makefile()
• recv()，recv_into() （但flags不允许传递非零参数）
• send()，sendall()（有同样的限制）
• sendfile()（但os.sendfile仅用于纯文本套接字，否则send()将使用）
• shutdown()

但是，由于SSL（和TLS）协议在TCP上具有自己的成帧，因此SSL套接字抽象在某些方面可能偏离正常的OS级别套接字的规范。请参阅有关 非阻塞套接字的说明。

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

SSL套接字还具有以下附加方法和属性：

SSLSocket.read（len = 1024，缓冲区=无）

从SSL套接字读取len个字节的数据，并将结果作为bytes实例返回。如果缓冲器被指定，然后读入到缓冲液代替，并返回读出的字节数。

提升SSLWantReadError或者SSLWantWriteError如果套接字是 非阻塞的，则读取将阻塞。

在任何时候都可以进行重新协商，调用read()也可以导致写操作。

SSLSocket.write（buf ）

将buf写入SSL套接字并返回写入的字节数。所述 的buf参数必须是支撑所述缓冲器接口的对象。

提升SSLWantReadError或者SSLWantWriteError如果套接字是 非阻塞的，则写入将阻塞。

在任何时候都可以进行重新协商，调用write()也可以导致读操作。

SSLSocket.do_handshake（）

执行SSL设置握手。

SSLSocket.getpeercert（binary_form = False ）

如果连接另一端没有对等体的证书，则返回None。如果尚未完成SSL握手，请提高 ValueError。

如果binary_form参数是False，并且从对等方收到证书，则此方法返回dict实例。如果证书未经过验证，则dict为空。如果证书已经过验证，它将返回一个带有几个密钥的dict，其中包括subject （颁发证书issuer 的委托人）和（颁发证书的委托人）。如果证书包含“ 使用者备用名称”扩展名的实例（请参阅RFC 3280），subjectAltName字典中也会有一个键。

的subject和issuer字段是包含在该证书的数据结构给出了各个场相对专有名称（的RDN）的序列的元组，并且每个RDN是名称-值对的序列。这是一个现实世界的例子：

{'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}

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

• 对于客户端SSL套接字，无论是否需要验证，服务器都将始终提供证书;
• 对于服务器SSL套接字，客户端仅在服务器请求时提供证书; 因此如果您使用（而不是 或）getpeercert()将返回 。NoneCERT_NONECERT_OPTIONALCERT_REQUIRED

SSLSocket.cipher（）

返回一个三值元组，其中包含正在使用的密码的名称，定义其使用的SSL协议的版本以及正在使用的密码位数。如果尚未建立连接，则返回None。

SSLSocket.shared_ciphers（）

返回握手期间客户端共享的密码列表。返回列表的每个条目都是一个三值元组，包含密码的名称，定义其使用的SSL协议的版本以及密码使用的秘密位数。 shared_ciphers()返回 None如果没有连接已经建立或者套接字的客户机套接字。

SSLSocket.compression（）

返回用作字符串的压缩算法，或者None 如果连接未压缩。

如果更高级别的协议支持其自己的压缩机制，则可以使用OP_NO_COMPRESSION禁用SSL级别压缩。

SSLSocket.get_channel_binding（cb_type =“tls-unique” ）

获取当前连接的通道绑定数据，作为字节对象。返回 None如果没有连接或握手尚未完成。

所述cb_type参数允许所需的信道绑定类型的选择。CHANNEL_BINDING_TYPES列表中列出了有效的通道绑定类型。目前只有'tls-unique'通道绑定，由。定义支持 RFC 5929。 ValueError如果请求不受支持的通道绑定类型，将引发此异常。

SSLSocket.selected_alpn_protocol（）

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

SSLSocket.selected_npn_protocol（）

返回在TLS / SSL握手期间选择的更高级别协议。如果SSLContext.set_npn_protocols()未被呼叫，或者另一方不支持NPN，或者握手尚未发生，则返回None。

SSLSocket.unwrap（）

执行SSL关闭握手，从基础套接字中删除TLS层，并返回基础套接字对象。这可用于从通过连接的加密操作转到未加密的。返回的套接字应始终用于与连接的另一端进行进一步通信，而不是原始套接字。

SSLSocket.verify_client_post_handshake（）

从TLS 1.3客户端请求握手后身份验证（PHA）。在初始TLS握手和双方都启用PHA之后，PHA只能从服务器端套接字启动TLS 1.3连接，请参阅 SSLContext.post_handshake_auth。

该方法不立即执行证书交换。服务器端在下一个写入事件期间发送CertificateRequest，并期望客户端在下一个读取事件时使用证书进行响应。

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

SSLSocket.version（）

将连接协商的实际SSL协议版本作为字符串返回，或者None没有建立安全连接。在撰写本文时，可能的返回值包括"SSLv2"， "SSLv3"，"TLSv1"，"TLSv1.1"和"TLSv1.2"。最近的OpenSSL版本可能会定义更多的返回值。

SSLSocket.pending（）

返回连接上可读取，待处理的已解密字节数。

SSLSocket.context

SSLContext此SSL套接字绑定的对象。如果SSL套接字是使用不推荐使用的wrap_socket()函数（而不是SSLContext.wrap_socket()）创建的，则这是为此SSL套接字创建的自定义上下文对象。

SSLSocket.server_side

一个布尔值，True用于服务器端套接字和False客户端套接字。

SSLSocket.server_hostname

服务器的主机名：str类型，或None服务器端套接字，或者在构造函数中未指定主机名。

SSLSocket.session

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

SSLSocket.session_reused

SSL上下文

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

class ssl.SSLContext（protocol = PROTOCOL_TLS ）

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

这是一个表格，显示客户端（侧面）中的哪些版本可以连接到服务器中的哪些版本（沿着顶部）：

客户 / 服务器	的SSLv2	在SSLv3	TLS [3]	使用TLSv1	TLSv1.1	TLSv1.2工作
的SSLv2	是	没有	没有[1]	没有	没有	没有
在SSLv3	没有	是	没有[2]	没有	没有	没有
TLS（SSLv23）[3]	没有[1]	没有[2]	是	是	是	是
使用TLSv1	没有	没有	是	是	没有	没有
TLSv1.1	没有	没有	是	没有	是	没有
TLSv1.2工作	没有	没有	是	没有	没有	是

脚注

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

SSLContext.cert_store_stats（）

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

具有一个CA证书和另一个证书的上下文的示例：

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

SSLContext.load_cert_chain（certfile，keyfile = None，password = None ）

加载私钥和相应的证书。所述certFile中 字符串必须的路径PEM格式包含证书以及任何号码，以建立证书的真实性所需要的CA证书的单个文件。该密钥文件的字符串，如果存在的话，必须指向包含私有密钥的文件，否则私钥将采取certFile中也是如此。有关证书如何存储在certfile中的更多信息，请参阅证书的讨论 。

该密码参数可以是一个函数来调用用于解密私钥获取密码。只有在加密私钥并且需要密码时才会调用它。它将在没有参数的情况下调用，它应该返回一个字符串，字节或字节数组。如果返回值是字符串，则在使用它来解密密钥之前，它将被编码为UTF-8。或者，可以直接提供字符串，字节或字节数值作为密码参数。如果私钥未加密且不需要密码，则将被忽略。

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

SSLError如果私钥与证书不匹配，则引发An 。

SSLContext.load_default_certs（目的= Purpose.SERVER_AUTH ）

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

该目的标志指定类型的CA证书加载什么。默认设置Purpose.SERVER_AUTH加载了TLS Web服务器身份验证（客户端套接字）标记和信任的证书。Purpose.CLIENT_AUTH在服务器端加载CA证书以进行客户端证书验证。

SSLContext.load_verify_locations（cafile = None，capath = None，cadata = None ）

加载一组“认证权威”一起使用时，以验证其他对等端的证书（CA）证书的verify_mode比其他 CERT_NONE。必须指定至少一个cafile或capath。

此方法还可以加载PEM或DER格式的认证撤销列表（CRL）。为了使用CRL，SSLContext.verify_flags 必须正确配置。

的凭证档案错误串，如果存在的话，是路径到PEM格式级联CA证书的文件。有关如何在此文件中排列证书的详细信息，请参阅证书的讨论 。

的capath串，如果存在的话，是路径到包含PEM格式几个CA证书，以下内容的一个目录的OpenSSL特定布局。

的cadata对象，如果存在的话，或者是一个或多个PEM编码证书的ASCII字符串或类字节对象 DER编码的证书。与capath一样，PEM编码证书周围的额外行被忽略，但必须至少存在一个证书。

SSLContext.get_ca_certs（binary_form = False ）

获取已加载的“证书颁发机构”（CA）证书的列表。如果 binary_form参数是False每个列表条目是一个像输出的字典SSLSocket.getpeercert()。否则，该方法返回DER编码证书列表。返回的列表不包含来自capath的证书，除非SSL连接请求并加载证书。

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及更新版本中，密码dict包含其他字段：

>>> 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+。

SSLContext.set_default_verify_paths（）

从构建OpenSSL库时定义的文件系统路径加载一组默认的“证书颁发机构”（CA）证书。不幸的是，没有简单的方法可以知道此方法是否成功：如果没有找到证书，则不会返回错误。但是，当OpenSSL库作为操作系统的一部分提供时，可能会正确配置。

SSLContext.set_ciphers（密码）

为使用此上下文创建的套接字设置可用密码。它应该是OpenSSL密码列表格式的字符串。如果不能选择密码（因为编译时选项或其他配置禁止使用所有指定的密码），SSLError将引发一个密码 。

SSLContext.set_alpn_protocols（协议）

指定套接字在SSL / TLS握手期间应通告的协议。它应该是一个ASCII字符串列表，例如，按优先顺序排序。协议的选择将在握手期间发生，并将根据情况发挥作用['http/1.1', 'spdy/2']RFC 7301。成功握手后，该SSLSocket.selected_alpn_protocol()方法将返回商定的协议。

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

SSLError 当双方都支持ALPN但无法就协议达成一致时，OpenSSL 1.1.0到1.1.0e将中止握手并提升。1.1.0f +表现得像1.0.2，SSLSocket.selected_alpn_protocol()返回None。

SSLContext.set_npn_protocols（协议）

指定套接字在SSL / TLS握手期间应通告的协议。它应该是一个字符串列表，例如，按优先顺序排序。协议的选择将在握手期间进行，并将根据应用层协议协商进行播放。成功握手后，该方法将返回商定的协议。['http/1.1', 'spdy/2']SSLSocket.selected_npn_protocol()

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

SSLContext.sni_callback

注册一个回调函数，当TLS客户端指定服务器名称指示时，SSL / TLS服务器收到TLS客户端Hello握手消息后将调用该函数。服务器名称指示机制在。中指定RFC 6066第3节 - 服务器名称指示。

每个只能设置一个回调SSLContext。如果 设置了sni_callback，None则禁用回调。随后调用此函数将禁用先前注册的回调。

回调函数将使用三个参数调用; 第一个是ssl.SSLSocket，第二个是表示客户端打算通信的服务器名称的字符串（或者None如果TLS客户端Hello不包含服务器名称），第三个参数是原始的SSLContext。服务器名称参数是文本。对于国际化域名，服务器名称是IDN A标签（"xn--pythn-mua.org"）。

此回调的典型用法是将ssl.SSLSockets SSLSocket.context属性更改为SSLContext表示与服务器名称匹配的证书链的新对象类型 。

由于TLS连接的早期协商阶段，只有有限的方法和属性可以使用 SSLSocket.selected_alpn_protocol()和SSLSocket.context。 SSLSocket.getpeercert()，SSLSocket.getpeercert()， SSLSocket.cipher()和SSLSocket.compress()方法要求TLS连接已经渐渐超越了TLS客户端问候，并因此将不包含返回有意义的值，也不能被安全地调用。

该sni_callback函数必须返回None允许TLS协商继续。如果需要TLS故障，ALERT_DESCRIPTION_*则可以返回常量 。其他返回值将导致TLS致命错误 ALERT_DESCRIPTION_INTERNAL_ERROR。

如果从sni_callback函数引发异常，则TLS连接将以致命的TLS警报消息终止ALERT_DESCRIPTION_HANDSHAKE_FAILURE。

NotImplementedError如果OpenSSL库在构建时定义了OPENSSL_NO_TLSEXT，则会引发此方法。

SSLContext.set_servername_callback（server_name_callback ）

这是为保持向后兼容性而保留的遗留API。如果可能，您应该使用sni_callback。给定的server_name_callback 类似于sni_callback，除了当服务器主机名是IDN编码的国际化域名时，server_name_callback 接收解码的U-label（"pythön.org"）。

如果服务器名称上存在解码错误，则TLS连接将终止，ALERT_DESCRIPTION_INTERNAL_ERROR并向客户端发送致命的TLS警报消息。

SSLContext.load_dh_params（dhfile ）

加载Diffie-Hellman（DH）密钥交换的密钥生成参数。使用DH密钥交换以牺牲计算资源（服务器和客户端）为代价提高了前向保密性。所述dhfile参数应的路径包含PEM格式DH参数的文件。

此设置不适用于客户端套接字。您还可以使用该 OP_SINGLE_DH_USE选项进一步提高安全性。

SSLContext.set_ecdh_curve（curve_name ）

设置基于Elliptic Curve的Diffie-Hellman（ECDH）密钥交换的曲线名称。ECDH明显快于常规DH，可以说是安全的。所述curve_name参数应该是字符串描述公知的椭圆曲线，例如prime256v1用于一个广泛支持曲线。

此设置不适用于客户端套接字。您还可以使用该 OP_SINGLE_ECDH_USE选项进一步提高安全性。

如果HAS_ECDH是，则此方法不可用False。

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_STREAM插座; 其他套接字类型不受支持。

该参数server_side是一个布尔值，用于标识此套接字是否需要服务器端或客户端行为。

对于客户端套接字，上下文构造是懒惰的; 如果底层套接字尚未连接，则connect()在套接字上调用后将执行上下文构造。对于服务器端套接字，如果套接字没有远程对等体，则假定它是侦听套接字，并且在通过该accept()方法接受的客户端连接上自动执行服务器端SSL包装 。该方法可能会提高SSLError。

在客户端连接上，可选参数server_hostname指定我们要连接的服务的主机名。这允许单个服务器使用不同的证书托管多个基于SSL的服务，与HTTP虚拟主机非常相似。如果server_side为true，则指定server_hostname将引发。ValueError

该参数do_handshake_on_connect指定在执行a后socket.connect()是否自动执行SSL握手，或者应用程序是否将通过调用SSLSocket.do_handshake()方法显式调用它 。SSLSocket.do_handshake()显式调用 使程序可以控制握手中涉及的套接字I / O的阻塞行为。

该参数suppress_ragged_eofs指定SSLSocket.recv()方法如何 从连接的另一端发出意外的EOF信号。如果指定为True（默认值），则返回正常的EOF（空字节对象）以响应从底层套接字引发的意外EOF错误; 如果False，它会将异常提回给调用者。

会议，见session。

SSLContext.sslsocket_class

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

SSLContext.wrap_bio（传入，传出，server_side = False，server_hostname =无，session =无）

包装传入和传出的BIO对象并返回attr的实例：SSLContext.sslobject_class（默认值SSLObject）。SSL例程将从传入的BIO读取输入数据并将数据写入传出BIO。

该server_side，server_hostname和会话参数具有相同的含义SSLContext.wrap_socket()。

SSLContext.sslobject_class

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

SSLContext.session_stats（）

获取有关此上下文创建或管理的SSL会话的统计信息。返回一个字典，它将每条信息的名称映射到它们的数值。例如，以下是自创建上下文以来会话缓存中的命中和未命中总数：

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

SSLContext.check_hostname

是否将对等证书的主机名与match_hostname()in 匹配SSLSocket.do_handshake()。上下文的 verify_mode必须设置为CERT_OPTIONAL或 CERT_REQUIRED，你必须通过server_hostname到 wrap_socket()为了匹配的主机名。启用主机自动检测设置verify_mode，从 CERT_NONE到CERT_REQUIRED。CERT_NONE只要启用了主机名检查，就无法将其设置回 。

例：

import socket, sslcontext = ssl.SSLContext()
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))

SSLContext.maximum_version

一个TLSVersion表示支持的最高TLS版本枚举成员。该值默认为TLSVersion.MAXIMUM_SUPPORTED。对于除PROTOCOL_TLS和PROTOCOL_TLS_CLIENT，和之外的协议， 该属性是只读的PROTOCOL_TLS_SERVER。

属性maximum_version， minimum_version并且 SSLContext.options所有影响环境的支持SSL和TLS版本。实现不会阻止无效组合。例如，具有OP_NO_TLSv1_2in options和 maximum_versionset 的上下文TLSVersion.TLSv1_2 将无法建立TLS 1.2连接。

SSLContext.minimum_version

喜欢SSLContext.maximum_version除了它是支持最低的版本或TLSVersion.MINIMUM_SUPPORTED。

SSLContext.options

一个整数，表示在此上下文中启用的SSL选项集。默认值为OP_ALL，但您可以指定其他选项，例如将OP_NO_SSLv2它们组合在一起。

>>> ssl.create_default_context().options  # doctest: +SKIP
<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.

SSLContext.protocol

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

SSLContext.hostname_checks_common_name

是否check_hostname在没有主题备用名称扩展名的情况下退回以验证证书的主题公用名（默认值：true）。

SSLContext.verify_flags

证书验证操作的标志。您可以VERIFY_CRL_CHECK_LEAF通过将它们组合在一起来设置标记 。默认情况下，OpenSSL既不需要也不验证证书吊销列表（CRL）。仅适用于openssl 0.9.8+版本。

>>> ssl.create_default_context().verify_flags  # doctest: +SKIP
<VerifyFlags.VERIFY_X509_TRUSTED_FIRST: 32768>

SSLContext.verify_mode

是否尝试验证其他对等方的证书以及验证失败时的行为方式。该属性必须是一个 CERT_NONE，CERT_OPTIONAL或CERT_REQUIRED。

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

证书

证书通常是公钥/私钥系统的一部分。在该系统中，每个主体（可以是机器，人或组织）被分配唯一的两部分加密密钥。密钥的一部分是公共的，称为公钥 ; 另一部分保密，称为私钥。这两部分是相关的，因为如果使用其中一个部分加密消息，则可以使用其他部分对其进行解密，并且仅对其他部分进行解密 。

证书包含有关两个主体的信息。它包含主题的名称和主题的公钥。它还包含第二个委托人，即发行人的声明，即主体是他们声称的主体，并且这确实是主体的公钥。发行人的声明是与发行人的私钥签订的，只有发行人才知道。但是，任何人都可以通过查找发行者的公钥，使用它解密语句，并将其与证书中的其他信息进行比较来验证发行者的声明。证书还包含有关其有效时间段的信息。这表示为两个字段，称为“notBefore”和“notAfter”。

在Python使用证书时，客户端或服务器可以使用证书来证明它们是谁。还可以要求网络连接的另一端产生证书，并且可以验证该证书以满足需要这种验证的客户端或服务器的要求。如果验证失败，可以将连接尝试设置为引发异常。验证由底层的OpenSSL框架自动完成; 应用程序不需要关注其机制。但是，应用程序通常需要提供一组证书才能允许此过程发生。

Python使用文件来包含证书。它们应格式化为“PEM”（参见RFC 1422），它是一个包含标题行和页脚行的base-64编码形式：

-----BEGIN CERTIFICATE-----
... (certificate in base64 PEM encoding) ...
-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----
... (certificate for your server)...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
... (the certificate for the CA)...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
... (the root certificate for the CA's issuer)...
-----END CERTIFICATE-----

-----BEGIN RSA PRIVATE KEY-----
... (private key in base64 encoding) ...
-----END RSA PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
... (certificate in base64 PEM encoding) ...
-----END CERTIFICATE-----

% openssl req -new -x509 -days 365 -nodes -out cert.pem -keyout cert.pem
Generating a 1024 bit RSA private key
.......++++++
.............................++++++
writing new private key to 'cert.pem'
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:MyState
Locality Name (eg, city) []:Some City
Organization Name (eg, company) [Internet Widgits Pty Ltd]:My Organization, Inc.
Organizational Unit Name (eg, section) []:My Group
Common Name (eg, YOUR name) []:myserver.mygroup.myorganization.com
Email Address []:ops@myserver.mygroup.myorganization.com
%

示例

try:import ssl
except ImportError:pass
else:...  # do something that requires SSL support

>>> context = ssl.create_default_context()

>>> context = ssl.SSLContext()
>>> context.verify_mode = ssl.CERT_REQUIRED
>>> context.check_hostname = True
>>> 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'']

import socket, sslcontext = 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)

while True: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()

def deal_with_client(connstream):data = connstream.recv(1024)# empty data means the client is finished with uswhile data:if not do_something(connstream, data):# we'll assume do_something returns False# when we're finished with clientbreakdata = connstream.recv(1024)# finished with client

关于非阻塞套接字的注释

在非阻塞模式下，SSL套接字的行为与常规套接字略有不同。使用非阻塞套接字时，您需要注意以下几点：

• 如果I / O操作会阻塞，大多数SSLSocket方法都会引发 SSLWantWriteError或SSLWantReadError代替BlockingIOError。SSLWantReadError如果需要对底层套接字执行读操作，并且SSLWantWriteError对底层套接字执行写操作，则会引发此操作。需要注意的是试图 写至SSL套接字可能需要读取从底层插座中，并试图读取从SSL套接字可能要求之前写入到底层插座。

  在3.5版中更改：在早期的Python版本中，该SSLSocket.send()方法返回零而不是引发SSLWantWriteError或SSLWantReadError。

• 调用select()告诉您可以从（或写入）读取OS级别的套接字，但这并不意味着上层SSL层有足够的数据。例如，只有部分SSL帧可能已到达。因此，您必须准备好处理SSLSocket.recv() 和SSLSocket.send()失败，并在另一次调用后重试 select()。

• 相反，由于SSL层具有自己的框架，因此SSL套接字可能仍然具有可用于读取的数据而select() 不会意识到它。因此，您应首先调用 SSLSocket.recv()以排出任何可能可用的数据，然后仅在select()必要时阻止呼叫。

  （当然，类似的规定适用于使用其他原语，例如模块poll()中的原语 selectors）

• SSL握手本身将是非阻塞的：SSLSocket.do_handshake()必须重试该 方法，直到它成功返回。这是一个select()用于等待套接字准备的概要：

  while True:try:sock.do_handshake()breakexcept ssl.SSLWantReadError:select.select([sock], [], [])except ssl.SSLWantWriteError:select.select([], [sock], [])
  

内存生成器支持

自从Python 2.6中引入SSL模块以来，SSLSocket 该类提供了两个相关但不同的功能区域：

• SSL协议处理
• 网络IO

网络IO API与提供的网络IO API相同socket.socket，SSLSocket也从中继承。这允许将SSL套接字用作常规套接字的替代品，从而可以非常轻松地向现有应用程序添加SSL支持。

将SSL协议处理和网络IO结合起来通常效果很好，但在某些情况下却没有。一个示例是异步IO框架，它们希望使用与“文件描述符上的选择/轮询”（基于准备就绪）模型不同的IO多路复用模型，该模型socket.socket 由内部OpenSSL套接字IO例程假设。这主要与Windows等平台无关，这种模式效率不高。为此目的，提供了一种缩小范围的SSLSocket被调用变体SSLObject。

类ssl.SSLObject

SSLSocket表示不包含任何网络IO方法的SSL协议实例的范围缩小的变体。此类通常由希望通过内存缓冲区为SSL实现异步IO的框架作者使用。

此类在OpenSSL实现的低级SSL对象之上实现接口。此对象捕获SSL连接的状态，但不提供任何网络IO本身。IO需要通过单独的“BIO”对象执行，这些对象是OpenSSL的IO抽象层。

这个类没有公共构造函数。一个SSLObject实例必须使用创建wrap_bio()方法。此方法将创建SSLObject实例并将其绑定到一对BIO。该传入 BIO用于从Python的数据传递到所述SSL协议实例，而传出 BIO用于围绕传递数据的其他方式。

可以使用以下方法：

• context
• server_side
• server_hostname
• session
• session_reused
• read()
• write()
• getpeercert()
• selected_npn_protocol()
• cipher()
• shared_ciphers()
• compression()
• pending()
• do_handshake()
• unwrap()
• get_channel_binding()

与之相比SSLSocket，此对象缺少以下功能：

• 任何形式的网络IO; recv()并且send()只对底层MemoryBIO缓冲区进行读写。
• 没有do_handshake_on_connect机制。您必须始终手动调用do_handshake()以开始握手。
• 没有处理suppress_ragged_eofs。通过SSLEOFError异常报告所有违反协议的文件结束条件 。
• 方法unwrap()调用不会返回任何内容，这与它返回底层套接字的SSL套接字不同。
• 传递给的server_name_callback回调 SSLContext.set_servername_callback()将获取SSLObject 实例而不是SSLSocket实例作为其第一个参数。

与使用有关的一些注意事项SSLObject：

• a上的所有IO SSLObject都是非阻塞的。这意味着，例如read()，SSLWantReadError如果它需要的数据多于传入的BIO可用数据，则会引发一个 数据。
• 没有wrap_bio()类似的模块级调用 wrap_socket()。一个SSLObject总是通过创建SSLContext。

SSLObject使用内存缓冲区与外界通信。该类MemoryBIO提供了可用于此目的的内存缓冲区。它包装了一个OpenSSL内存BIO（基本IO）对象：

类ssl.MemoryBIO

一种内存缓冲区，可用于在Python和SSL协议实例之间传递数据。

pending

返回内存缓冲区中当前的字节数。

eof

一个布尔值，指示存储器BIO在文件末尾位置是否是当前的。

read（n = -1 ）

从内存缓冲区读取最多n个字节。如果未指定n或为负，则返回所有字节。

write（buf ）

将buf中的字节写入内存BIO。所述的buf参数必须是支持缓冲协议的对象。

返回值是写入的字节数，总是等于buf的长度。

write_eof（）

将EOF标记写入内存BIO。调用此方法后，调用是非法的write()。eof读取当前缓冲区中的所有数据后，该属性将变为true。

SSL会话

类ssl.SSLSession

使用的Session对象session。

id

time

timeout

ticket_lifetime_hint

has_ticket

安全考虑

>>> import ssl, smtplib
>>> smtp = smtplib.SMTP("mail.python.org", port=587)
>>> context = ssl.create_default_context()
>>> smtp.starttls(context=context)
(220, b'2.0.0 Ready to start TLS')

>>> client_context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
>>> client_context.options |= ssl.OP_NO_TLSv1
>>> client_context.options |= ssl.OP_NO_TLSv1_1

TLS 1.3

Python对OpenSSL 1.1.1的TLS 1.3提供了临时和实验支持。新协议的行为与先前版本的TLS / SSL略有不同。一些新的TLS 1.3功能尚不可用。

• TLS 1.3使用一组分离的密码套件。默认情况下，所有AES-GCM和ChaCha20密码套件均已启用。该方法SSLContext.set_ciphers()无法启用或禁用任何TLS 1.3密码，但会SSLContext.get_ciphers()返回它们。
• 会话票证不再作为初始握手的一部分发送，并且处理方式不同。 SSLSocket.session并且SSLSession 与TLS 1.3不兼容。
• 在初始握手期间，也不再验证客户端证书。服务器可以随时请求证书。客户端在从服务器发送或接收应用程序数据时处理证书请求。
• 尚不支持TLS 1.3功能，如早期数据，延迟TLS客户端证书请求，签名算法配置和密钥更新。

LibreSSL支持

LibreSSL是OpenSSL 1.0.1的一个分支。ssl模块对LibreSSL的支持有限。使用LibreSSL编译ssl模块时，某些功能不可用。

• LibreSSL> = 2.6.1不再支持NPN。这些方法 SSLContext.set_npn_protocols()和SSLSocket.selected_npn_protocol()不可用。
• SSLContext.set_default_verify_paths() 忽略env vars SSL_CERT_FILE 和 SSL_CERT_PATH虽然get_default_verify_paths()仍然报道他们。