docs/library/ssl: Add documentation for SSLContext.

Signed-off-by: Damien George <damien@micropython.org>

1 files changed, 45 insertions, 17 deletions

diff --git a/docs/library/ssl.rst b/docs/library/ssl.rst
index 924b03b35..e3dfa9d99 100644
--- a/docs/library/ssl.rst
+++ b/docs/library/ssl.rst
@@ -15,36 +15,53 @@ Functions
 
 .. function:: ssl.wrap_socket(sock, server_side=False, keyfile=None, certfile=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
+----------------
+
+.. class:: SSLContext(protocol, /)
+
+    Create a new SSLContext instance.  The *protocol* argument must be one of the ``PROTOCOL_*``
+    constants.
+
+.. 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),
-   and returns an instance of ssl.SSLSocket, which wraps the underlying stream in
-   an SSL context. Returned object has the usual `stream` interface methods like
+   and returns an instance of ssl.SSLSocket, wrapping the underlying stream.
+   The returned object has the usual `stream` interface methods like
    ``read()``, ``write()``, etc.
-   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* determines whether the handshake is done as part of the ``wrap_socket``
+   - *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
-     (there is no ``do_handshake`` method as in CPython).
      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.
 
-   - *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.
-
    - *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.
 
-   Depending on the underlying module implementation in a particular
-   :term:`MicroPython port`, some or all keyword arguments above may be not supported.
-
 .. warning::
 
    Some implementations of ``ssl`` module do NOT validate server certificates,
@@ -55,6 +72,11 @@ Functions
    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.
+
 Exceptions
 ----------
 
@@ -65,8 +87,14 @@ Exceptions
 Constants
 ---------
 
+.. data:: ssl.PROTOCOL_TLS_CLIENT
+          ssl.PROTOCOL_TLS_SERVER
+
+    Supported values for the *protocol* parameter.
+
 .. data:: ssl.CERT_NONE
           ssl.CERT_OPTIONAL
           ssl.CERT_REQUIRED
 
-    Supported values for *cert_reqs* parameter.
+    Supported values for *cert_reqs* parameter, and the :attr:`SSLContext.verify_mode`
+    attribute.