Skip to content

gh-154517: Document OpenSSL version requirements and post-quantum groups for the ssl group API #154518

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
fedonman wants to merge 3 commits into
base: main
Choose a base branch
from
+28 −0
Open

gh-154517: Document OpenSSL version requirements and post-quantum groups for the ssl group API #154518

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2940b06
gh-154517: Document OpenSSL version requirements and post-quantum gro…
fedonman Jul 23, 2026
97975e0
gh-154517: Add myself to Misc/ACKS
fedonman Jul 23, 2026
e56cc61
Merge branch 'main' into docs-ssl-pqc-groups
fedonman Jul 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions Doc/library/ssl.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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()
Expand Down Expand Up @@ -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()
Expand Down Expand Up @@ -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
<https://docs.openssl.org/master/man3/SSL_CTX_set1_groups_list/>`_.

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
Expand Down Expand Up @@ -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::
Expand Down Expand Up @@ -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.
Expand Down
1 change: 1 addition & 0 deletions Misc/ACKS
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading