From 12025f0979c3e6db68b58618b8021647eb42560c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Dani=C3=ABl=20van=20de=20Giessen?= <daniel@dvdgiessen.nl>
Date: Tue, 19 Mar 2024 16:38:19 +0100
Subject: [PATCH] extmod/modtls_mbedtls: Documentation of SSLSession support.
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Daniël van de Giessen <daniel@dvdgiessen.nl>
---
 docs/library/ssl.rst | 23 +++++++++++++++++++++--
 1 file changed, 21 insertions(+), 2 deletions(-)

diff --git a/docs/library/ssl.rst b/docs/library/ssl.rst
index dff90b8da5..d54331a189 100644
--- a/docs/library/ssl.rst
+++ b/docs/library/ssl.rst
@@ -13,7 +13,7 @@ facilities for network sockets, both client-side and server-side.
 Functions
 ---------
 
-.. function:: ssl.wrap_socket(sock, server_side=False, key=None, cert=None, cert_reqs=CERT_NONE, cadata=None, server_hostname=None, do_handshake=True)
+.. function:: ssl.wrap_socket(sock, server_side=False, key=None, cert=None, cert_reqs=CERT_NONE, cadata=None, server_hostname=None, do_handshake=True, session=None)
 
     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`
@@ -28,6 +28,9 @@ Functions
    - *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.
 
+   - *session* allows a client socket to reuse a session by passing a SSLSession object
+     previously retrieved from the ``session`` property of a wrapped-socket object.
+
    Depending on the underlying module implementation in a particular
    :term:`MicroPython port`, some or all keyword arguments above may be not supported.
 
@@ -66,7 +69,7 @@ class SSLContext
    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)
+.. method:: SSLContext.wrap_socket(sock, *, server_side=False, do_handshake_on_connect=True, server_hostname=None, session=None)
 
    Takes a `stream` *sock* (usually socket.socket instance of ``SOCK_STREAM`` type),
    and returns an instance of ssl.SSLSocket, wrapping the underlying stream.
@@ -89,6 +92,9 @@ class SSLContext
      server certificate.  It also sets the name for Server Name Indication (SNI), allowing the server
      to present the proper certificate.
 
+   - *session* allows a client socket to reuse a session by passing a SSLSession object
+     previously retrieved from the ``session`` property of a ssl.SSLSocket object.
+
 .. warning::
 
    Some implementations of ``ssl`` module do NOT validate server certificates,
@@ -110,6 +116,19 @@ class SSLContext
    `mpremote rtc --set <mpremote_command_rtc>` or ``ntptime``, and ``server_hostname``
    must be specified when on the client side.
 
+class SSLSession
+----------------
+
+.. class:: SSLSession(buf)
+
+    This constructor is a MicroPython extension to reconstruct a SSLSession object using
+    a bytes object previously returned by the ``serialize`` method.
+
+.. method:: SSLSession.serialize()
+
+   This function is a MicroPython extension to return a bytes object representing the
+   session, allowing it to be stored and reconstructed at a later time.
+
 Exceptions
 ----------