gh-137197: Add SSLContext.set_ciphersuites to set TLS 1.3 ciphers #137198

ronf · 2025-07-29T05:07:16Z

This commit adds a new method SSLContext.set_ciphersuites which can be used to set TLS 1.3 cipher suites. It also updates the documentation, unit tests, and "what's new" text. A NEWS blurb will be added shortly.

Issue: Add support in SSL module for getting/setting TLS 1.3 cipher suites #137197

📚 Documentation preview 📚: https://cpython-previews--137198.org.readthedocs.build/

gpshead · 2025-07-29T05:25:51Z

Modules/_ssl.c

@@ -3595,12 +3595,27 @@ _ssl__SSLContext_set_ciphers_impl(PySSLContext *self, const char *cipherlist)
 {
    int ret = SSL_CTX_set_cipher_list(self->ctx, cipherlist);
    if (ret == 0) {
-        /* Clearing the error queue is necessary on some OpenSSL versions,


We shouldn't remove this without understanding which OpenSSL versions it was referring to and whether they are still in use by CPython builds (1.1.x-ish API'd AWS-LC at a minimum, otherwise OpenSSL 3.0+).

The clearing of the error queue is still happening here. I just took advantage of an existing helper function setSSLError to take care of this:

static PyObject * _setSSLError (_sslmodulestate *state, const char *errstr, int errcode, const char *filename, int lineno) { if (errstr == NULL) errcode = ERR_peek_last_error(); else errcode = 0; fill_and_set_sslerror(state, NULL, state->PySSLErrorObject, errcode, errstr, lineno, errcode); ERR_clear_error(); return NULL; }

Doc/library/ssl.rst

Doc/whatsnew/3.15.rst

picnixz · 2025-07-29T07:53:32Z

Doc/whatsnew/3.15.rst

+* Added new method :meth:`ssl.SSLContext.set_ciphersuites` for setting TLS 1.3
+  ciphers and updated the documentation on :meth:`ssl.SSLContext.set_ciphers`
+  to mention that it only applies to TLS 1.2 and earlier and that this new
+  method must be used to set TLS 1.3 cipher suites.


Suggested change

* Added new method :meth:`ssl.SSLContext.set_ciphersuites` for setting TLS 1.3

ciphers and updated the documentation on :meth:`ssl.SSLContext.set_ciphers`

to mention that it only applies to TLS 1.2 and earlier and that this new

method must be used to set TLS 1.3 cipher suites.

* Added new method :meth:`ssl.SSLContext.set_ciphersuites` for setting TLS 1.3

ciphers. For TLS 1.2 or earlier, use :meth:`ssl.SSLContext.set_ciphers` instead.

What do you think about changing the text here to something like:

* Added new method :meth:`ssl.SSLContext.set_ciphersuites` for setting TLS 1.3 ciphers. For TLS 1.2 or earlier, :meth:`ssl.SSLContext.set_ciphers` should continue to be used. Both calls can be made on the same context and the selected cipher suite will depend on the TLS version negotiated when a connection is made.

I wanted to somehow capture that these calls aren't mutually exclusive if you don't know in advance what version of TLS will end up being used. The existing call only affects cipher suites chosen when TLS 1.2 or earlier is negotiated, and the new call only affects cipher suites chosen when TLS 1.3 is negotiated.

@picnixz, are you ok with this new wording?

I've checked in the new wording I proposed. Let me know if you want any changes here.

I think this change may be ready to go if there are no other review comments.

Sorry, I forgot about this PR and I missed the notification I think. Let me have a look again.

Clarify when to use the original set_ciphers (TLS 1.2 and earlier) vs. the new set_ciphersuites (TLS 1.3) methods and that both can be used at once.

picnixz · 2025-08-09T08:39:07Z

Doc/library/ssl.rst

-   <https://docs.openssl.org/master/man1/ciphers/>`_.
-   If no cipher can be selected (because compile-time options or other
+   Set the allowed ciphers for sockets created with this context when
+   connecting using TLS 1.2 and earlier.  It should be a string in the `OpenSSL


Suggested change

connecting using TLS 1.2 and earlier. It should be a string in the `OpenSSL

connecting using TLS 1.2 and earlier. *ciphers* should be a string in the `OpenSSL

I think it's better to say what's "it" is. I personally understand but removing any possible ambiguity would be better anyway. Up to you though. Same for ciphersuites below

picnixz · 2025-08-09T08:39:28Z

Doc/library/ssl.rst

+   To set allowed TLS 1.3 ciphers, use :meth:`SSLContext.set_ciphersuites`.
+   below.  If no cipher can be selected (because compile-time options or other


Suggested change

To set allowed TLS 1.3 ciphers, use :meth:`SSLContext.set_ciphersuites`.

below. If no cipher can be selected (because compile-time options or other

To set allowed TLS 1.3 ciphers, use :meth:`SSLContext.set_ciphersuites`.

If no cipher can be selected (because compile-time options or other

picnixz · 2025-08-09T08:41:06Z

Doc/library/ssl.rst

   configuration forbids use of all the specified ciphers), an
   :class:`SSLError` will be raised.

   .. note::
      when connected, the :meth:`SSLSocket.cipher` method of SSL sockets will
-      give the currently selected cipher.
+      return the negotiated cipher and associated TLS version.


The docstring actually says:

"""Return the currently selected cipher as a 3-tuple ``(name, ssl_version, secret_bits)``."""

So it's not a pair but a triplet that is being returned (that's how it's implemented in C). I suggest that we make this doc change in a separate PR.

picnixz · 2025-08-09T08:45:49Z

Lib/test/test_ssl.py

-                     cert_reqs=ssl.CERT_NONE, ca_certs=None,
-                     ciphers=None, certfile=None, keyfile=None,
-                     **kwargs):
+def test_wrap_socket(sock, *, cert_reqs=ssl.CERT_NONE, ca_certs=None,


Maybe revert the linebreak changes (namely keep sock, * on its own line) and just add ciphersuites and min_version after ciphers, and put certfile and keyfile on their own lines as well.

picnixz · 2025-08-09T08:47:03Z

Lib/test/test_ssl.py

+                              min_version=ssl.TLSVersion.TLSv1_3) as s:
+            s.connect(self.server_addr)
+            self.assertEqual(s.cipher()[1], "TLSv1.3")
+        with test_wrap_socket(socket.socket(socket.AF_INET),


What about builds that don't support TLS 1.3?

picnixz · 2025-08-09T08:47:24Z

Lib/test/test_ssl.py

@@ -2109,6 +2112,28 @@ def test_ciphers(self):
                                    cert_reqs=ssl.CERT_NONE, ciphers="^$:,;?*'dorothyx")
                s.connect(self.server_addr)

+    def test_ciphersuites(self):


Shouldn't we ensure that this test is run for builds with TLS 1.3?

picnixz · 2025-08-09T08:48:13Z

Lib/test/test_ssl.py

+            s.connect(self.server_addr)
+            self.assertEqual(s.cipher(),
+                             ("TLS_AES_256_GCM_SHA384", "TLSv1.3", 256))
+        # Error checking can happen at instantiation or when connecting


When does it happen upon instantiation and when does it happen while connecting? is it possible to only raise when we do s.connect or only raise when we create the socket?

ronf requested review from gpshead and picnixz as code owners July 29, 2025 05:07

bedevere-app bot added the awaiting review label Jul 29, 2025

bedevere-app bot mentioned this pull request Jul 29, 2025

Add support in SSL module for getting/setting TLS 1.3 cipher suites #137197

Open

gpshead reviewed Jul 29, 2025

View reviewed changes

picnixz reviewed Jul 29, 2025

View reviewed changes

ronf requested a review from AA-Turner as a code owner August 9, 2025 00:23

ronf and others added 4 commits August 8, 2025 18:00

pythongh-137197: Add SSLContext.set_ciphersuites to set TLS 1.3 ciphers

5a1cc22

📜🤖 Added by blurb_it.

09534fd

pythongh-137197: Fix typo in documentation

6783fe6

pythongh-137197: Update what's new text

d3375f1

Clarify when to use the original set_ciphers (TLS 1.2 and earlier) vs. the new set_ciphersuites (TLS 1.3) methods and that both can be used at once.

ronf force-pushed the ssl-ciphersuite-support branch from f2cda88 to d3375f1 Compare August 9, 2025 01:00

picnixz reviewed Aug 9, 2025

View reviewed changes

	connecting using TLS 1.2 and earlier. It should be a string in the `OpenSSL
	connecting using TLS 1.2 and earlier. ciphers should be a string in the `OpenSSL

		To set allowed TLS 1.3 ciphers, use :meth:`SSLContext.set_ciphersuites`.
		below. If no cipher can be selected (because compile-time options or other

Uh oh!

gh-137197: Add SSLContext.set_ciphersuites to set TLS 1.3 ciphers #137198

Are you sure you want to change the base?

gh-137197: Add SSLContext.set_ciphersuites to set TLS 1.3 ciphers #137198

Conversation

ronf commented Jul 29, 2025 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

picnixz Aug 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

ronf commented Jul 29, 2025 •

edited by github-actions bot

Loading

picnixz Aug 9, 2025 •

edited

Loading