diff options
| author | Keenan Johnson <keenan.johnson@gmail.com> | 2025-02-13 13:11:38 -0800 |
|---|---|---|
| committer | Damien George <damien@micropython.org> | 2025-02-14 12:55:25 +1100 |
| commit | 321b30ca564bb33c625292247d00f7dd29dc9559 (patch) | |
| tree | 34f04febf16e5825f069b002494dd512b0c30331 /docs/library | |
| parent | aef6705a321fbefb06288b5be1f5931bf8c42fe3 (diff) | |
extmod/modtls_mbedtls: Wire in support for DTLS.
This commit enables support for DTLS, i.e. TLS over datagram transport
protocols like UDP. While support for DTLS is absent in CPython, it is
worth supporting it in MicroPython because it is the basis of the
ubiquitous CoAP protocol, used in many IoT projects.
To select DTLS, a new set of "protocols" are added to SSLContext:
- ssl.PROTOCOL_DTLS_CLIENT
- ssl.PROTOCOL_DTLS_SERVER
If one of these is set, the library assumes that the underlying socket is a
datagram-like socket (i.e. UDP or similar).
Our own timer callbacks are implemented because the out of the box
implementation relies on `gettimeofday()`.
This new DTLS feature is enabled on all ports that use mbedTLS.
This commit is an update to a previous PR #10062.
Addresses issue #5270 which requested DTLS support.
Signed-off-by: Keenan Johnson <keenan.johnson@gmail.com>
Diffstat (limited to 'docs/library')
| -rw-r--r-- | docs/library/ssl.rst | 21 |
1 files changed, 21 insertions, 0 deletions
diff --git a/docs/library/ssl.rst b/docs/library/ssl.rst index dff90b8da..4327c74ba 100644 --- a/docs/library/ssl.rst +++ b/docs/library/ssl.rst @@ -117,11 +117,32 @@ Exceptions This exception does NOT exist. Instead its base class, OSError, is used. +DTLS support +------------ + +.. admonition:: Difference to CPython + :class: attention + + This is a MicroPython extension. + +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 mbed TLS, and it is not enabled by default: +it requires enabling ``MBEDTLS_SSL_PROTO_DTLS`` in the specific port configuration. + Constants --------- .. 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. |