docs/library/ssl.rst
ssl -- SSL/TLS module.. module:: ssl :synopsis: TLS/SSL wrapper for socket objects
|see_cpython_module| :mod:python: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.
.. function:: 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
:term:MicroPython port, some or all keyword arguments above may be not supported.
.. class:: SSLContext(protocol, /)
Create a new SSLContext instance. The *protocol* argument must be one of the ``PROTOCOL_*``
constants.
.. method:: 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.
.. admonition:: Difference to CPython :class: attention
MicroPython extension: *certfile* and *keyfile* can be bytes objects instead of
strings, in which case they are interpreted as the actual certificate/key data.
.. method:: 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.
.. method:: SSLContext.get_ciphers()
Get a list of enabled ciphers, returned as a list of strings.
.. method:: 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 <https://wiki.mozilla.org/Security/Cipher_Suites>_ .
.. method:: 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
:meth:~socket.socket.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 :ref:dtls 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.
.. attribute:: 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 <mpremote_command_rtc> or ntptime, and server_hostname
must be specified when on the client side.
.. data:: ssl.SSLError
This exception does NOT exist. Instead its base class, OSError, is used.
.. _dtls:
.. admonition:: Difference to CPython :class: attention
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.
.. data:: 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.
.. data:: ssl.CERT_NONE ssl.CERT_OPTIONAL ssl.CERT_REQUIRED
Supported values for *cert_reqs* parameter, and the :attr:`SSLContext.verify_mode`
attribute.