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

 {
    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; }

Let's keep it that way and change it in a follow-up PR instead. Actually, the errcode parameter for _setSSLError is redundant as it's always overwritten.

Doc/library/ssl.rst

Doc/whatsnew/3.15.rst

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.

Doc/library/ssl.rst

Lib/test/test_ssl.py

ronf · 2025-08-09T18:04:55Z

I think all the remaining review comments should be addressed in 48e5164. Let me know if you'd like any other changes.

Doc/library/ssl.rst

Doc/whatsnew/3.15.rst

Lib/test/test_ssl.py

This commit reworks the set_ciphersuites() test cases, moving them into their own class to avoid any changes to existing tests. It also makes the cipher selection dynamic to avoid potentially trying to use a cipher not available in some environments.

ronf · 2025-08-16T00:07:58Z

@picnixz, any further changes required? The build failure appears to be something in the test runner, as the only thing changed in the last checkin was capitalization in the docs. Prior to that, all tests succeeded.

picnixz · 2025-08-16T12:33:43Z

I'm not available before next week but I'll have a look.

ronf · 2025-08-17T05:22:56Z

That'd be great - thanks!

I spent some time today working on adding methods to manage signature algorithms and will create a new issue & PR for those as soon as these changes are merged.

Doc/library/ssl.rst

picnixz · 2025-08-18T10:52:59Z

Doc/library/ssl.rst

-  ciphers yet, but :meth:`SSLContext.get_ciphers` returns them.
+- TLS 1.3 uses a disjunct set of cipher suites.  All AES-GCM and ChaCha20
+  cipher suites are enabled by default.  To restrict which TLS1.3 ciphers
+  are allowed, the method :meth:`SSLContext.set_ciphersuites` should be


For posterity: I really hate that OpenSSL named it SSL_CTX_set_ciphersuites for TLS 1.3 and later, and SSL_CTX_set_cipher_list for TLS 1.2 and below. I hope that this won't be annoying to users.

I was surprised what they did here at first and I'm not a big fan about the naming chosen, but I can see why they didn't want to try and extend the existing command. It allows all kinds of partial matches on the five individual elements that make up a cipher suite in TLS 1.2 and earlier, plus other special keywords like LOW/MEDIUM/HIGH. All of that is gone with TLS 1.3, and the new function is much simpler and only supports an exact match against the very small number of cipher suites defined in TLS 1.3.

I don't really know why they didn't include "_list" in the name of the OpenSSL function, given that this seems to be the convention for other such calls that take a string argument.

The good news here is that things like post-quantum crypto are going to drive migration to TLS 1.3, and at some point setting TLS 1.2 cipher suites will no longer matter. At that point, the previous set_ciphers() can be deprecated and eventually removed, with only set_ciphersuites() remaining.

Lib/test/test_ssl.py

picnixz · 2025-08-18T11:06:01Z

Modules/_ssl.c

 {
    int ret = SSL_CTX_set_cipher_list(self->ctx, cipherlist);
    if (ret == 0) {
-        /* Clearing the error queue is necessary on some OpenSSL versions,


Let's keep it that way and change it in a follow-up PR instead. Actually, the errcode parameter for _setSSLError is redundant as it's always overwritten.

ronf · 2025-08-21T03:03:28Z

Thanks for your review! I think I've addressed this round of review comments, including reverting the change to _ssl__SSLContext_set_ciphers_impl for now. Let me know if anything else is needed.

ronf · 2025-08-28T02:28:40Z

Just checking in - are there any further changes you'd like me to make?

picnixz

Just a few nitpicks.

Doc/library/ssl.rst

Doc/whatsnew/3.15.rst

Lib/test/test_ssl.py

Misc/NEWS.d/next/Library/2025-07-29-05-12-50.gh-issue-137197.bMK3sO.rst

Modules/_ssl.c

picnixz

A final nitpick and we're good to go I think

Lib/test/test_ssl.py

ronf · 2025-08-29T19:50:18Z

I've gone ahead and created issue #138252 in preparation for the next round of changes, to add support for getting and setting TLS signature algorithms. I have those changes ready, but will hold off until this change is merged before I submit the PR, to avoid any merge conflicts.

picnixz

I'm going to amend it directly and merge this.

Doc/whatsnew/3.15.rst

picnixz · 2025-08-30T08:59:16Z

Lib/test/test_ssl.py

            self.assertRaises(ssl.SSLEOFError, sslobj.read)


+@unittest.skipUnless(has_tls_version('TLSv1_3'), "TLS 1.3 is not available")


Note to myself: change the requires_tls_version decorator so that it works.

Lib/test/test_ssl.py

picnixz · 2025-08-30T09:05:50Z

Lib/test/test_ssl.py

+                              min_version=ssl.TLSVersion.TLSv1_2,
+                              max_version=ssl.TLSVersion.TLSv1_2) as s:
+            s.connect(self.server_addr)
+            self.assertEqual(s.cipher()[1], 'TLSv1.2')


This test is asserting that the default TLSv1_2 cipher suite is actually being used right? I'm fine with the current test but I'd like to fortify it (which I'll do) in the future where we have a ciphersuite for TLSv1.3 and a ciphersuite for TLSv1.2 and if we use min/max versions, then we're going to be using the TLSv1.2 ciphersuite we specified.

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

Closed

gpshead reviewed Jul 29, 2025

View reviewed changes

picnixz reviewed Jul 29, 2025

View reviewed changes

Doc/whatsnew/3.15.rst Outdated Show resolved Hide resolved

Doc/whatsnew/3.15.rst Outdated Show resolved Hide resolved

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

pythongh-137197: Address review comments

48e5164

picnixz reviewed Aug 9, 2025

View reviewed changes

Doc/library/ssl.rst Show resolved Hide resolved

Doc/whatsnew/3.15.rst Outdated Show resolved Hide resolved

Lib/test/test_ssl.py Outdated Show resolved Hide resolved

Lib/test/test_ssl.py Outdated Show resolved Hide resolved

ronf added 2 commits August 9, 2025 13:23

pythongh-137197: Rework test cases

11b760e

This commit reworks the set_ciphersuites() test cases, moving them into their own class to avoid any changes to existing tests. It also makes the cipher selection dynamic to avoid potentially trying to use a cipher not available in some environments.

pythongh-137197: Fix capitalization in docs

eaae575

picnixz self-assigned this Aug 16, 2025

picnixz self-requested a review August 18, 2025 10:36

picnixz reviewed Aug 18, 2025

View reviewed changes

pythongh-137197: Address review comments

e09017f

picnixz self-requested a review August 22, 2025 08:11

picnixz reviewed Aug 28, 2025

View reviewed changes

pythongh-137197: Address review comments

caf6675

picnixz approved these changes Aug 29, 2025

View reviewed changes

Lib/test/test_ssl.py Outdated Show resolved Hide resolved

bedevere-app bot added awaiting merge and removed awaiting review labels Aug 29, 2025

pythongh-137197: Address last review comment

fe8791d

picnixz approved these changes Aug 30, 2025

View reviewed changes

Apply suggestions from code review

4566478

picnixz enabled auto-merge (squash) August 30, 2025 09:12

picnixz merged commit bacb777 into python:main Aug 30, 2025
45 checks passed

bedevere-app bot removed the awaiting merge label Aug 30, 2025

ronf deleted the ssl-ciphersuite-support branch August 30, 2025 15:57

picnixz mentioned this pull request Sep 8, 2025

Improve usage of _setSSLError in _ssl.c #138634

Open

3 tasks

		self.assertRaises(ssl.SSLEOFError, sslobj.read)


		@unittest.skipUnless(has_tls_version('TLSv1_3'), "TLS 1.3 is not available")

Uh oh!

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

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

Uh oh!

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!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ronf commented Aug 9, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ronf commented Aug 16, 2025

Uh oh!

picnixz commented Aug 16, 2025

Uh oh!

ronf commented Aug 17, 2025

Uh oh!

Uh oh!

Uh oh!

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!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ronf commented Aug 21, 2025

Uh oh!

ronf commented Aug 28, 2025

Uh oh!

picnixz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

picnixz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ronf commented Aug 29, 2025

Uh oh!

picnixz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ronf commented Jul 29, 2025 •

edited by github-actions bot

Loading