diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst index 66fe6c7aee4862..084484d8e3a00d 100644 --- a/Doc/library/ssl.rst +++ b/Doc/library/ssl.rst @@ -1315,6 +1315,9 @@ SSL sockets also have the following additional methods and attributes: Return the group used for doing key agreement on this connection. If no connection has been established, returns ``None``. + This method requires OpenSSL 3.2 or later; it raises + :exc:`NotImplementedError` when linked against an older version. + .. versionadded:: 3.15 .. method:: SSLSocket.client_sigalg() @@ -1707,6 +1710,9 @@ to speed up repeated connections from the same clients. :const:`True` this method will also return any associated aliases such as the ECDH curve names supported in older versions of OpenSSL. + This method requires OpenSSL 3.5 or later; it raises + :exc:`NotImplementedError` when linked against an older version. + .. versionadded:: 3.15 .. method:: SSLContext.set_default_verify_paths() @@ -1754,6 +1760,19 @@ to speed up repeated connections from the same clients. context. It should be a string in the `OpenSSL group list format `_. + This is a more general replacement for :meth:`~SSLContext.set_ecdh_curve`: + it accepts several groups in order of preference and supports finite-field + and post-quantum hybrid groups in addition to ECDH curves. For example, + to prefer the post-quantum hybrid group ``X25519MLKEM768`` and fall back + to the classical ``X25519`` group:: + + >>> ctx = ssl.create_default_context() + >>> ctx.set_groups("X25519MLKEM768:X25519") # doctest: +SKIP + + Post-quantum hybrid groups such as ``X25519MLKEM768`` require OpenSSL 3.5 + or later. Requesting a group that the linked OpenSSL does not recognize + raises an :class:`SSLError`. + .. note:: When connected, the :meth:`SSLSocket.group` method of SSL sockets will @@ -1911,6 +1930,10 @@ to speed up repeated connections from the same clients. This method is not available if :data:`HAS_ECDH` is ``False``. + For more control, including selecting several groups in order of + preference or offering post-quantum hybrid groups, use the more general + :meth:`~SSLContext.set_groups` method. + .. versionadded:: 3.3 .. seealso:: @@ -2933,6 +2956,10 @@ of TLS/SSL. Some new TLS 1.3 features are not yet available. and the method :meth:`SSLSocket.cipher` returns information about the negotiated cipher for both TLS 1.3 and earlier versions once a connection is established. +- Key agreement can use post-quantum hybrid groups such as + ``X25519MLKEM768`` when linked against OpenSSL 3.5 or later, which offers + them by default. Use :meth:`SSLContext.set_groups` to choose which groups + are offered and :meth:`SSLSocket.group` to see which one was negotiated. - Session tickets are no longer sent as part of the initial handshake and are handled differently. :attr:`SSLSocket.session` and :class:`SSLSession` are not compatible with TLS 1.3. diff --git a/Misc/ACKS b/Misc/ACKS index fec00c1b272f4e..5fe1d8cd1121ee 100644 --- a/Misc/ACKS +++ b/Misc/ACKS @@ -2008,6 +2008,7 @@ Wm. Keith van der Meulen Eric N. Vander Weele Andrew Vant Atul Varma +Vyron Vasileiadis Dmitry Vasiliev Sebastian Ortiz Vasquez Alexandre Vassalotti