This is the v1.26.0 version of the MicroPython documentation. The latest development version of this page may be more current.

`ssl` – SSL/TLS module¶

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

This module provides access to Transport Layer Security (previously and widely known as “Secure Sockets Layer”) encryption and peer authentication facilities for network sockets, both client-side and server-side.

Functions¶

ssl.wrap_socket(sock, server_side=False, key=None, cert=None, cert_reqs=CERT_NONE, cadata=None, server_hostname=None, do_handshake=True)¶

Wrap the given sock and return a new wrapped-socket object. The implementation of this function is to first create an SSLContext and then call the SSLContext.wrap_socket method on that context object. The arguments sock, server_side and server_hostname are passed through unchanged to the method call. The argument do_handshake is passed through as do_handshake_on_connect. The remaining arguments have the following behaviour:

cert_reqs determines whether the peer (server or client) must present a valid certificate. Note that for mbedtls based ports, ssl.CERT_NONE and ssl.CERT_OPTIONAL will not validate any certificate, only ssl.CERT_REQUIRED will.
cadata is a bytes object containing the CA certificate chain (in DER format) that will validate the peer’s certificate. Currently only a single DER-encoded certificate is supported.

Depending on the underlying module implementation in a particular MicroPython port, some or all keyword arguments above may be not supported.

class SSLContext¶

class ssl.SSLContext(protocol, /)¶: Create a new SSLContext instance. The protocol argument must be one of the PROTOCOL_* constants.

SSLContext.load_cert_chain(certfile, keyfile)¶: Load a private key and the corresponding certificate. The certfile is a string with the file path of the certificate. The keyfile is a string with the file path of the private key.

Difference to CPython

MicroPython extension: certfile and keyfile can be bytes objects instead of strings, in which case they are interpreted as the actual certificate/key data.

SSLContext.load_verify_locations(cafile=None, cadata=None)¶: Load the CA certificate chain that will validate the peer’s certificate. cafile is the file path of the CA certificates. cadata is a bytes object containing the CA certificates. Only one of these arguments should be provided.

SSLContext.get_ciphers()¶: Get a list of enabled ciphers, returned as a list of strings.

SSLContext.set_ciphers(ciphers)¶: Set the available ciphers for sockets created with this context. ciphers should be a list of strings in the IANA cipher suite format .

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

Takes a stream sock (usually socket.socket instance of SOCK_STREAM type), and returns an instance of ssl.SSLSocket, wrapping the underlying stream. The returned object has the usual stream interface methods like read(), write(), etc.

server_side selects whether the wrapped socket is on the server or client side. A server-side SSL socket should be created from a normal socket returned from accept() on a non-SSL listening server socket.
do_handshake_on_connect determines whether the handshake is done as part of the wrap_socket or whether it is deferred to be done as part of the initial reads or writes For blocking sockets doing the handshake immediately is standard. For non-blocking sockets (i.e. when the sock passed into wrap_socket is in non-blocking mode) the handshake should generally be deferred because otherwise wrap_socket blocks until it completes. Note that in AXTLS the handshake can be deferred until the first read or write but it then blocks until completion.
server_hostname is for use as a client, and sets the hostname to check against the received server certificate. It also sets the name for Server Name Indication (SNI), allowing the server to present the proper certificate.
client_id is a MicroPython-specific extension argument used only when implementing a DTLS Server. See DTLS support for details.

Warning

Some implementations of ssl module do NOT validate server certificates, which makes an SSL connection established prone to man-in-the-middle attacks.

CPython’s wrap_socket returns an SSLSocket object which has methods typical for sockets, such as send, recv, etc. MicroPython’s wrap_socket returns an object more similar to CPython’s SSLObject which does not have these socket methods.

SSLContext.verify_mode¶: Set or get the behaviour for verification of peer certificates. Must be one of the CERT_* constants.

Note

ssl.CERT_REQUIRED requires the device’s date/time to be properly set, e.g. using mpremote rtc --set or ntptime, and server_hostname must be specified when on the client side.

Exceptions¶

ssl.SSLError¶: This exception does NOT exist. Instead its base class, OSError, is used.

DTLS support¶

Difference to CPython

This is a MicroPython extension.

On most ports, this module supports DTLS in client and server mode via the PROTOCOL_DTLS_CLIENT and PROTOCOL_DTLS_SERVER constants that can be used as the protocol argument of SSLContext.

In this case the underlying socket is expected to behave as a datagram socket (i.e. like the socket opened with socket.socket with socket.AF_INET as af and socket.SOCK_DGRAM as type).

DTLS is only supported on ports that use mbedTLS, and it is enabled by default in most configurations but can be manually disabled by defining MICROPY_PY_SSL_DTLS to 0.

DTLS server support¶

MicroPython’s DTLS server support is configured with “Hello Verify” as required for DTLS 1.2. This is transparent for DTLS clients, but there are relevant considerations when implementing a DTLS server in MicroPython:

The server should pass an additional argument client_id when calling SSLContext.wrap_socket(). This ID must be a bytes object (or similar) with a transport-specific identifier representing the client.

The simplest approach is to convert the tuple of (client_ip, client_port) returned from socket.recv_from() into a byte string, i.e.:
```
_, client_addr = sock.recvfrom(1, socket.MSG_PEEK)
sock.connect(client_addr)  # Connect back to the client
sock = ssl_ctx.wrap_socket(sock, server_side=True,
                           client_id=repr(client_addr).encode())
```
The first time a client connects, the server call to wrap_socket will fail with a OSError error “Hello Verify Required”. This is because the DTLS “Hello Verify” cookie is not yet known by the client. If the same client connects a second time then wrap_socket will succeed.
DTLS cookies for “Hello Verify” are associated with the SSLContext object, so the same SSLContext object should be used to wrap a subsequent connection from the same client. The cookie implementation includes a timeout and has constant memory use regardless of how many clients connect, so it’s OK to reuse the same SSLContext object for the lifetime of the server.

Constants¶

ssl.PROTOCOL_TLS_CLIENT¶
ssl.PROTOCOL_TLS_SERVER¶
ssl.PROTOCOL_DTLS_CLIENT(when DTLS support is enabled)¶
ssl.PROTOCOL_DTLS_SERVER(when DTLS support is enabled)¶: Supported values for the protocol parameter.

ssl.CERT_NONE¶
ssl.CERT_OPTIONAL¶
ssl.CERT_REQUIRED¶: Supported values for cert_reqs parameter, and the SSLContext.verify_mode attribute.

ssl – SSL/TLS module¶