Python SSL操作手册

ssl —套接字对象的 TLS/SSL 包装器

此模块提供对 Client 端和服务器端网络套接字的传输层安全性(通常称为“安全套接字层”)加密和对等身份验证Function的访问。该模块使用 OpenSSL 库。只要在该平台上安装了 OpenSSL，它就可以在所有现代 Unix 系统，Windows，Mac OS X 以及可能的其他平台上使用。

Note

由于对 os 套接字 API 进行了调用，因此某些行为可能取决于平台。安装的 OpenSSL 版本也可能导致行为变化。例如，TLSv1.1 和 TLSv1.2 随附 openssl 版本 1.0.1.

Warning

请勿在未阅读Security considerations的情况下使用此模块。这样做可能会导致错误的安全感，因为 ssl 模块的默认设置不一定适合您的应用程序。

开始

本节记录了ssl模块中的对象和Function；有关 TLS，SSL 和证书的更多常规信息，请参阅底部“另请参阅”部分中的文档。

此模块提供了一个类ssl.SSLSocket，该类派生自socket.socket类型，并提供类似于套接字的包装器，该包装器还使用 SSL 对pass套接字的数据进行加密和解密。它支持其他方法，例如getpeercert()(用于检索连接另一侧的证书)和cipher()(用于检索用于安全连接的密码)。

对于更复杂的应用程序，ssl.SSLContext类有助于 Management 设置和证书，然后可以passpass SSLContext.wrap_socket() 方法创建的 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.

函数，常量和异常

Socket creation
从 Python 3.2 和 2.7.9 开始，建议使用SSLContext实例的 SSLContext.wrap_socket() 将套接字包装为SSLSocket对象。辅助函数 create_default_context() 返回具有安全默认设置的新上下文。不推荐使用旧的 wrap_socket() 函数，因为它既效率低下，也不支持服务器名称指示(SNI)和主机名匹配。

具有默认上下文和 IPv4/IPv6 双栈的 Client 端套接字示例：

import socket
import ssl

hostname = '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())

具有自定义上下文和 IPv4 的 Client 端套接字示例：

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())

侦听 localhost IPv4 的服务器套接字示例：

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()
        ...

Context creation

便利Function可帮助创建SSLContext对象以用于常见目的。

ssl. create_default_context(* purpose = Purpose.SERVER_AUTH ， cafile = None ， capath = None ， cadata = None *)
/
返回具有给定用途的默认设置的新 SSLContext 对象。这些设置由ssl模块选择，通常代表比直接调用SSLContext构造函数更高的安全级别。

cafile ， capath ， cadata * 代表可选的 CA 证书，可信任该证书以进行证书验证，如SSLContext.load_verify_locations()。如果所有三个均为None，则此函数可以选择信任系统的默认 CA 证书。

设置为： 具有高加密密码套件的 PROTOCOL_TLS ，OP_NO_SSLv2 和 OP_NO_SSLv3 ，而 RC4 和未经身份验证的密码套件。将SERVER_AUTH用作目的会将verify_mode设置为CERT_REQUIRED并加载 CA 证书(当至少给出* cafile ， capath 或 cadata * 之一时)或使用SSLContext.load_default_certs()加载默认的 CA 证书。

如果支持keylog_filename并且设置了环境变量 SSLKEYLOGFILE，则create_default_context()启用键记录。

Note

协议，选项，密码和其他设置可以随时更改为更具限制性的值，而无需事先弃用。这些值表示兼容性和安全性之间的合理平衡。

如果您的应用程序需要特定的设置，则应创建一个SSLContext并自己应用设置。

Note

如果您发现某些较旧的 Client 端或服务器try与此Function创建的SSLContext进行连接时收到错误消息，指出“协议或密码套件不匹配”，则可能是它们仅支持 SSL3.0，但此Function不使用OP_NO_SSLv3。 SSL3.0 被广泛认为是completely broken。如果您仍然希望 continue 使用此Function但仍允许 SSL 3.0 连接，则可以使用以下方法重新启用它们：

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

版本更替：

3.4 版的新Function。
在版本 3.4.4 中更改：从默认密码字符串中删除了 RC4.
在版本 3.6 中更改：ChaCha20/Poly1305 已添加到默认密码字符串。
从默认密码字符串中删除了 3 DES。
在 3.8 版中进行了更改：添加了对到 SSLKEYLOGFILE的密钥记录的支持。

Exceptions

exception ssl. SSLError

引发 signal 以指示来自基础 SSL 实现的错误(当前由 OpenSSL 库提供)。这表示在底层网络连接上叠加的更高级别的加密和身份验证层中存在一些问题。此错误是OSError的子类型。 OpenSSL 库提供了SSLError个实例的错误代码和消息。

在版本 3.3 中更改：SSLError曾经是socket.error的子类型。

library

一个字符串助记符，指定发生错误的 OpenSSL 子模块，例如SSL，PEM或X509。可能值的范围取决于 OpenSSL 版本。

版本 3.3 中的新Function。

reason

一个字符串助记符，指示发生此错误的原因，例如CERTIFICATE_VERIFY_FAILED。可能值的范围取决于 OpenSSL 版本。

版本 3.3 中的新Function。

exception ssl. SSLZeroReturnError
try读取或写入时引发了SSLError的子类，并且 SSL 连接已完全关闭。请注意，这并不意味着基础传输(读取 TCP)已关闭。
版本 3.3 中的新Function。

exception ssl. SSLWantReadError

try读取或写入数据时，由非阻塞 SSL 套接字引发的SSLError子类，但是在满足请求之前，需要在基础 TCP 传输上接收更多数据。

版本 3.3 中的新Function。

exception ssl. SSLWantWriteError

try读取或写入数据时由非阻塞 SSL 套接字引发的SSLError子类，但是在满足请求之前，需要在基础 TCP 传输上发送更多数据。
版本 3.3 中的新Function。

exception ssl. SSLSyscallError

try在 SSL 套接字上执行操作时遇到系统错误时，将引发SSLError的子类。不幸的是，没有简单的方法来检查原始的 errno 号。
版本 3.3 中的新Function。

exception ssl. SSLEOFError

SSL 连接突然终止时引发的SSLError子类。通常，遇到此错误时，您不应try重用基础传输。
版本 3.3 中的新Function。

exception ssl. SSLCertVerificationError

证书验证失败时引发的SSLError子类。
3.7 版中的新Function。

verify_code
表示验证错误的数字错误编号。
verify_message
可读的验证错误字符串。
exception ssl. CertificateError

SSLCertVerificationError的别名。
在版本 3.7 中更改：现在，exception 是SSLCertVerificationError的别名。

Random generation
ssl. RAND_bytes(* num )
返回 num *个加密强度高的伪随机字节。如果 PRNG 尚未填充足够的数据或当前 RAND 方法不支持该操作，则引发SSLError。 RAND_status()可用于检查 PRNG 的状态，而RAND_add()可用于播种 PRNG。
对于几乎所有应用程序os.urandom()都是可取的。

阅读 Wikipedia 文章加密安全的伪随机数生成器(CSPRNG)，以获取密码生成器的要求。

版本 3.3 中的新Function。

ssl. RAND_pseudo_bytes(* num )
返回值(字节，is_cryptographic)：字节是 num *个伪随机字节，如果生成的字节在密码上很强，则 is_cryptographic 为True。如果当前 RAND 方法不支持该操作，则引发SSLError。
如果生成的伪随机字节序列具有足够的长度，则它们将是唯一的，但不一定是不可预测的。它们可以用于非加密目的，也可以用于加密协议中的某些目的，但通常不用于密钥生成等。

对于几乎所有应用程序os.urandom()都是可取的。

版本 3.3 中的新Function。

从 3.6 版开始弃用：OpenSSL 已弃用ssl.RAND_pseudo_bytes()，而改用ssl.RAND_bytes()。

ssl. RAND_status ( )

如果已经为 SSL 伪随机数生成器提供了“足够”的随机性，则返回True，否则返回False。您可以使用ssl.RAND_egd()和ssl.RAND_add()来增加伪随机数生成器的随机性。
ssl. RAND_egd(* path *)

如果您在某个地方运行熵收集守护程序(EGD)，并且* path *是向其打开的套接字连接的路径名，则它将从套接字读取 256 个字节的随机性，并将其添加到 SSL 伪随机数中生成器以增加生成的 Secret 密钥的安全性。通常只有在没有更好随机性的系统上才需要这样做。
有关熵收集守护程序的来源，请参见http://egd.sourceforge.net/或http://prngd.sourceforge.net/。

Availability：不适用于 LibreSSL 和 OpenSSL> 1.1.0.

ssl. RAND_add(* bytes ， entropy )
将给定的 bytes 混合到 SSL 伪随机数生成器中。参数 entropy *(浮点数)是字符串中包含的熵的下限(因此您可以始终使用0.0)。有关熵来源的更多信息，请参见 RFC 1750。
在版本 3.5 中更改：现在接受可写bytes-like object。

Certificate handling
ssl. match_hostname(* cert ， hostname )
验证 cert (以SSLSocket.getpeercert()返回的解码格式)匹配给定的 hostname *。所应用的规则是 RFC 2818， RFC 5280和 RFC 6125中概述的用于检查 HTTPS 服务器身份的规则。除 HTTPS 之外，此Function还应适用于检查各种基于 SSL 的协议(例如 FTPS，IMAPS，POPS 等)中服务器的身份。
失败时引发CertificateError。成功时，该函数不返回任何内容：

cert = {‘subject’: (((‘commonName’, ‘example.com’),),)}
ssl.match_hostname(cert, “example.com”)
ssl.match_hostname(cert, “example.org”)
Traceback (most recent call last):
File “”, line 1, in
File “/home/py3k/Lib/ssl.py”, line 130, in match_hostname
ssl.CertificateError: hostname ‘example.org’ doesn’t match ‘example.com’
3.2 版中的新Function。

在版本 3.3.3 中进行了更改：该函数现在遵循 RFC 6125(第 6.4.3 节)，并且既不匹配多个通配符(例如*..com或a*.example.org)，也不匹配国际化域名(IDN)片段内的通配符。仍支持 IDN A 标签，例如www*.xn–pthon-kva.org&#x