ssl – SSL/TLS 模块

This module implements a subset of the corresponding CPython module, as described below. For more information, refer to the original CPython documentation: ssl。

该模块提供了对传输层安全性（以前和广泛称为“安全套接字层”）加密和对等身份验证功能的访问，用于网络套接字，包括客户端和服务器端。

函数

ssl.wrap_socket(sock, server_side=False, keyfile=None, certfile=None, cert_reqs=CERT_NONE, cadata=None, server_hostname=None, do_handshake=True)

包装给定的 sock 并返回一个新的包装套接字对象。此函数的实现是首先创建一个 SSLContext ，然后在该上下文对象上调用 SSLContext.wrap_socket 方法。参数 sock 、 server_side 和 server_hostname 未经修改地传递给方法调用。参数 do_handshake 传递为 do_handshake_on_connect 。其余参数具有以下行为：

• cert_reqs 决定对等端（服务器或客户端）是否必须提供有效证书。请注意，对于基于 mbedtls 的移植版本，ssl.CERT_NONE 和 ssl.CERT_OPTIONAL 将不会验证任何证书，只有 ssl.CERT_REQUIRED 会。

• cadata 是一个包含 CA 证书链（DER 格式）的字节对象，该链将验证对等体的证书。当前仅支持单个 DER 编码的证书。

根据特定 MicroPython移植版本 中的底层模块实现，上述一些或全部关键字参数可能不受支持。

类 SSLContext

class ssl.SSLContext(protocol, /)

创建一个新的 SSLContext 实例。 protocol 参数必须是 PROTOCOL_* 常量之一。

SSLContext.load_cert_chain(certfile, keyfile)

加载私钥和相应的证书。 certfile 是包含证书文件路径的字符串。 keyfile 是包含私钥文件路径的字符串。

与CPython的不同之处

MicroPython扩展：certfile 和 keyfile 可以是字节对象，而不是字符串，这种情况下，它们被解释为实际的证书/密钥数据。

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

加载将验证对等体证书的CA证书链。 cafile 是 CA 证书的文件路径。 cadata 是一个包含 CA 证书的字节对象。应该只提供这些参数中的一个。

SSLContext.get_ciphers()

获取启用的密码列表，作为字符串列表返回。

SSLContext.set_ciphers(ciphers)

为使用此上下文创建的套接字设置可用密码。 ciphers 应该是 IANA密码套件格式 中的字符串列表。

SSLContext.wrap_socket(sock, *, server_side=False, do_handshake_on_connect=True, server_hostname=None)

接受一个 stream *sock*（通常是 SOCK_STREAM 类型的 socket.socket 实例），并返回一个 ssl.SSLSocket 的实例，用于包装底层流。返回的对象具有像 read()、write() 等的常规 stream 接口方法。

• server_side 选择包装套接字是服务器端还是客户端。服务器端的SSL套接字应该从非SSL监听服务器套接字的 accept() 返回的普通套接字创建。

• do_handshake_on_connect 确定是否在 wrap_socket 的一部分进行握手，或者是否推迟到作为初始读取或写入的一部分进行。对于立即执行握手的阻塞套接字是标准的。对于非阻塞套接字（即传递给 wrap_socket 的 sock 处于非阻塞模式时），握手通常应该推迟，因为否则 wrap_socket 将阻塞，直到完成。请注意，在AXTLS中，握手可以推迟到第一次读取或写入，但然后它会阻塞直到完成。

• server_hostname 用于作为客户端使用，并设置要与收到的服务器证书进行验证的主机名。它还设置了Server Name Indication（SNI）的名称，允许服务器呈现适当的证书。

警告

一些 ssl 模块的实现不验证服务器证书，这使得建立的SSL连接容易受到中间人攻击。

CPython 的 wrap_socket 返回一个 SSLSocket 对象，该对象具有类似套接字的方法，如 send、recv 等。MicroPython 的 wrap_socket 返回一个更类似于 CPython 的 SSLObject 的对象，该对象没有这些套接字方法。

SSLContext.verify_mode

设置或获取对等证书验证行为。必须是 CERT_* 常量之一。

备注

ssl.CERT_REQUIRED 要求设备的日期/时间正确设置，例如使用 mpremote rtc --set 或 ntptime，并且在客户端时必须指定 server_hostname。

异常

ssl.SSLError

不存在此异常。相反，使用其基类，OSError。

常量

ssl.PROTOCOL_TLS_CLIENT

ssl.PROTOCOL_TLS_SERVER

protocol 参数支持的值。

ssl.CERT_NONE

ssl.CERT_OPTIONAL

ssl.CERT_REQUIRED

cert_reqs 参数支持的值，以及 SSLContext.verify_mode 属性。