bpo-34670: Add TLS 1.3 post handshake auth (GH-9460)
Add SSLContext.post_handshake_auth and
SSLSocket.verify_client_post_handshake for TLS 1.3 post-handshake
authentication.
Signed-off-by: Christian Heimes <christian@python.org>q
https://bugs.python.org/issue34670
diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst
index 99d1d77..a8cbe23 100644
--- a/Doc/library/ssl.rst
+++ b/Doc/library/ssl.rst
@@ -1314,6 +1314,26 @@
returned socket should always be used for further communication with the
other side of the connection, rather than the original socket.
+.. method:: SSLSocket.verify_client_post_handshake()
+
+ Requests post-handshake authentication (PHA) from a TLS 1.3 client. PHA
+ can only be initiated for a TLS 1.3 connection from a server-side socket,
+ after the initial TLS handshake and with PHA enabled on both sides, see
+ :attr:`SSLContext.post_handshake_auth`.
+
+ The method does not perform a cert exchange immediately. The server-side
+ sends a CertificateRequest during the next write event and expects the
+ client to respond with a certificate on the next read event.
+
+ If any precondition isn't met (e.g. not TLS 1.3, PHA not enabled), an
+ :exc:`SSLError` is raised.
+
+ .. versionadded:: 3.8
+
+ .. note::
+ Only available with OpenSSL 1.1.1 and TLS 1.3 enabled. Without TLS 1.3
+ support, the method raises :exc:`NotImplementedError`.
+
.. method:: SSLSocket.version()
Return the actual SSL protocol version negotiated by the connection
@@ -1929,6 +1949,28 @@
>>> ssl.create_default_context().options # doctest: +SKIP
<Options.OP_ALL|OP_NO_SSLv3|OP_NO_SSLv2|OP_NO_COMPRESSION: 2197947391>
+.. attribute:: SSLContext.post_handshake_auth
+
+ Enable TLS 1.3 post-handshake client authentication. Post-handshake auth
+ is disabled by default and a server can only request a TLS client
+ certificate during the initial handshake. When enabled, a server may
+ request a TLS client certificate at any time after the handshake.
+
+ When enabled on client-side sockets, the client signals the server that
+ it supports post-handshake authentication.
+
+ When enabled on server-side sockets, :attr:`SSLContext.verify_mode` must
+ be set to :data:`CERT_OPTIONAL` or :data:`CERT_REQUIRED`, too. The
+ actual client cert exchange is delayed until
+ :meth:`SSLSocket.verify_client_post_handshake` is called and some I/O is
+ performed.
+
+ .. versionadded:: 3.8
+
+ .. note::
+ Only available with OpenSSL 1.1.1 and TLS 1.3 enabled. Without TLS 1.3
+ support, the property value is None and can't be modified
+
.. attribute:: SSLContext.protocol
The protocol version chosen when constructing the context. This attribute