docs/library: Document SSLContext cert methods and asyncio support.

Carglglz · dpgeorge · commit 05d3b223011a · 2023-12-14T13:06:39.000+11:00
Add `load_cert_chain`, `load_verify_locations`, `get_ciphers` and
`set_ciphers` SSLContext methods in ssl library, and update asyncio
`open_connection` and `start_server` methods with ssl support.

Signed-off-by: Carlos Gil &lt;carlosgilglez@gmail.com&gt;
diff --git a/docs/library/asyncio.rst b/docs/library/asyncio.rst
@@ -201,23 +201,27 @@ class Lock
 TCP stream connections
 ----------------------
 
-.. function:: open_connection(host, port)
+.. function:: open_connection(host, port, ssl=None)
 
     Open a TCP connection to the given *host* and *port*.  The *host* address will be
     resolved using `socket.getaddrinfo`, which is currently a blocking call.
+    If *ssl* is a `ssl.SSLContext` object, this context is used to create the transport;
+    if *ssl* is ``True``, a default context is used.
 
     Returns a pair of streams: a reader and a writer stream.
     Will raise a socket-specific ``OSError`` if the host could not be resolved or if
     the connection could not be made.
 
     This is a coroutine.
 
-.. function:: start_server(callback, host, port, backlog=5)
+.. function:: start_server(callback, host, port, backlog=5, ssl=None)
 
     Start a TCP server on the given *host* and *port*.  The *callback* will be
     called with incoming, accepted connections, and be passed 2 arguments: reader
     and writer streams for the connection.
 
+    If *ssl* is a `ssl.SSLContext` object, this context is used to create the transport.
+
     Returns a `Server` object.
 
     This is a coroutine.
diff --git a/docs/library/ssl.rst b/docs/library/ssl.rst
@@ -39,6 +39,33 @@ class SSLContext
     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)
 
    Takes a `stream` *sock* (usually socket.socket instance of ``SOCK_STREAM`` type),
@@ -77,6 +104,12 @@ class SSLContext
     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.
+
 Exceptions
 ----------
 
