Issue #19500: Add client-side SSL session resumption to the ssl module.

1 files changed, 47 insertions, 4 deletions

diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst
index af0c5ab..e942f44 100644
--- a/Doc/library/ssl.rst
+++ b/Doc/library/ssl.rst
@@ -776,6 +776,10 @@ Constants
 
    :class:`enum.IntFlag` collection of OP_* constants.
 
+.. data:: OP_NO_TICKET
+
+   Prevent client side from requesting a session ticket.
+
    .. versionadded:: 3.6
 
 .. data:: HAS_ALPN
@@ -1176,6 +1180,19 @@ SSL sockets also have the following additional methods and attributes:
 
    .. versionadded:: 3.2
 
+.. attribute:: SSLSocket.session
+
+   The :class:`SSLSession` for this SSL connection. The session is available
+   for client and server side sockets after the TLS handshake has been
+   performed. For client sockets the session can be set before
+   :meth:`~SSLSocket.do_handshake` has been called to reuse a session.
+
+   .. versionadded:: 3.6
+
+.. attribute:: SSLSocket.session_reused
+
+   .. versionadded:: 3.6
+
 
 SSL Contexts
 ------------
@@ -1509,7 +1526,7 @@ to speed up repeated connections from the same clients.
 
 .. method:: SSLContext.wrap_socket(sock, server_side=False, \
       do_handshake_on_connect=True, suppress_ragged_eofs=True, \
-      server_hostname=None)
+      server_hostname=None, session=None)
 
    Wrap an existing Python socket *sock* and return an :class:`SSLSocket`
    object.  *sock* must be a :data:`~socket.SOCK_STREAM` socket; other socket
@@ -1526,19 +1543,27 @@ to speed up repeated connections from the same clients.
    quite similarly to HTTP virtual hosts. Specifying *server_hostname* will
    raise a :exc:`ValueError` if *server_side* is true.
 
+   *session*, see :attr:`~SSLSocket.session`.
+
    .. versionchanged:: 3.5
       Always allow a server_hostname to be passed, even if OpenSSL does not
       have SNI.
 
+   .. versionchanged:: 3.6
+      *session* argument was added.
+
 .. method:: SSLContext.wrap_bio(incoming, outgoing, server_side=False, \
-                                server_hostname=None)
+                                server_hostname=None, session=None)
 
    Create a new :class:`SSLObject` instance by wrapping the BIO objects
    *incoming* and *outgoing*. The SSL routines will read input data from the
    incoming BIO and write data to the outgoing BIO.
 
-   The *server_side* and *server_hostname* parameters have the same meaning as
-   in :meth:`SSLContext.wrap_socket`.
+   The *server_side*, *server_hostname* and *session* parameters have the
+   same meaning as in :meth:`SSLContext.wrap_socket`.
+
+   .. versionchanged:: 3.6
+      *session* argument was added.
 
 .. method:: SSLContext.session_stats()
 
@@ -2045,6 +2070,8 @@ provided.
    - :attr:`~SSLSocket.context`
    - :attr:`~SSLSocket.server_side`
    - :attr:`~SSLSocket.server_hostname`
+   - :attr:`~SSLSocket.session`
+   - :attr:`~SSLSocket.session_reused`
    - :meth:`~SSLSocket.read`
    - :meth:`~SSLSocket.write`
    - :meth:`~SSLSocket.getpeercert`
@@ -2126,6 +2153,22 @@ purpose.  It wraps an OpenSSL memory BIO (Basic IO) object:
       become true after all data currently in the buffer has been read.
 
 
+SSL session
+-----------
+
+.. versionadded:: 3.6
+
+.. class:: SSLSession
+
+   Session object used by :attr:`~SSLSocket.session`.
+
+   .. attribute:: id
+   .. attribute:: time
+   .. attribute:: timeout
+   .. attribute:: ticket_lifetime_hint
+   .. attribute:: has_ticket
+
+
 .. _ssl-security:
 
 Security considerations