gh-89730: EncryptedClientHello support in ssl module #135435

irl · 2025-06-12T15:58:11Z

Exposes options for clients to use Encrypted Client Hello (ECH) when establishing TLS connections. It is up to the user to source the ECH public keys before making use of these options.

To use these options requires a version of openssl that includes these options, which currently are on a feature branch:

https://github.com/openssl/openssl/tree/feature/ech

We do not expect that the API here will have any substaintial changes when it is merged.

For testing, clone the above repository, checkout the feature/ech branch, and build. Then use this openssl installation when building cPython:

git clone https://github.com/openssl/openssl.git
pushd openssl
git checkout feature/ech
./configure --prefix=$HOME/opt/openssl
make -j8
make install_sw
popd
git clone https://github.com/irl/cpython.git
git checkout issue-89730
./configure --with-pydebug --with-openssl=$HOME/opt/openssl
make -j8

Additionally I have added to the documentation an example of the use of these options, which is built at: https://irl.github.io/cpython/library/ssl.html#encrypted-client-hello

Issue: Support TLS Encrypted ClientHello (ECH) #89730

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

python-cla-bot · 2025-06-12T15:58:14Z

All commit authors signed the Contributor License Agreement.

Modules/_ssl.c

picnixz

As you mentioned, the ECH feature is not yet available in OpenSSL (https://github.com/openssl/openssl/tree/feature/ech). I would like to defer this until it's released.

In addition:

please remove blank lines as much as possile. Too many blank lines hinder the reading flow.
check return codes from OpenSSL (SSL_ech_get1_retry_config may fail for instance, so you should check if it succeeded, and if not, correctly handle the return code)
we need tests

Doc/library/ssl.rst

picnixz · 2025-06-13T16:20:07Z

Misc/NEWS.d/next/Library/2025-06-12-15-39-48.gh-issue-89730.Lu35Fu.rst

+Adds support for Encrypted Client Hello (ECH) to the ssl module. Clients may
+use the options exposed to establish TLS connections using ECH. Third-party
+libraries like dnspython can be used to query for HTTPS and SVCB records
+that contain the public keys required to use ECH with specific servers. If
+no public key is available, an option is available to "GREASE" the
+connection, and it is possible to retrieve the public key from the retry
+configuration sent by servers that support ECH as they terminate the initial
+connection.


This description should also be put in What's New rather here.

I don't know what this means.

Misc/NEWS.d/next/Library/2025-06-12-15-39-48.gh-issue-89730.Lu35Fu.rst

Modules/_ssl.c

Lib/ssl.py

bedevere-app · 2025-06-13T16:46:07Z

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

Exposes options for clients to use Encrypted Client Hello (ECH) when establishing TLS connections. It is up to the user to source the ECH public keys before making use of these options.

AdamKorcz · 2025-12-30T13:08:28Z

Modules/_ssl.c

+    if (es_in == NULL) {
+        goto fail;
+    }
+    es = OSSL_ECHSTORE_new(NULL, NULL));


Double closing parenthesis looks like a typo.

AdamKorcz · 2025-12-30T13:13:52Z

Modules/_ssl.c

+    if (retval == NULL) {
+        goto fail;
+    }
+    PyTuple_SET_ITEM(retval, 0, PyLong_FromLong(status));


nit: PyLong_FromLong can return NULL. Should execution continue in that case?

No indeed, so this should be checked.

AdamKorcz · 2025-12-30T13:22:11Z

Modules/_ssl.c

+        Py_INCREF(Py_None);
+    }
+    return retval;
+fail:


FWICS retval needs to be free'd to in fail.

AdamKorcz · 2025-12-30T14:17:44Z

Doc/library/ssl.rst

+            context.set_ech_config(ech_config)
+        with socket.create_connection((hostname, 443)) as sock:
+            with context.wrap_socket(sock, server_hostname=hostname) as ssock:
+                if (ssock.get_ech_status == ECHStatus.ECH_STATUS_GREASE_ECH


This will always resolve to False because it is checking ssock.get_ech_status as a bound method object and not the result of the method. It should be ssock.get_ech_status().

picnixz

Considering it's still not released in OpenSSL, I prefer that we close this PR and re-open it once it's shipped. There are also conflicts to solve and the implementation is lacking tests and there is no ETA for that feature (we also need to find another way to configure this, because I'm not really happy with the configure check, we may need more checks with OPENSSL_VERSION for instance).

picnixz · 2025-12-30T15:52:17Z

Modules/_ssl.c

+    if (retval == NULL) {
+        goto fail;
+    }
+    PyTuple_SET_ITEM(retval, 0, PyLong_FromLong(status));


No indeed, so this should be checked.

picnixz · 2025-12-30T15:56:39Z

Modules/_ssl.c

+/*[clinic end generated code: output=cea53188b338cf80 input=3ef0514cae6ab6ee]*/
+{
+#ifdef HAVE_OPENSSL_ECH
+    BIO *es_in = BIO_new_mem_buf(ech_config->buf, ech_config->len);


can we avoid cryptic variable names please?

picnixz · 2025-12-30T15:56:58Z

Modules/_ssl.c

+    Py_RETURN_NONE;
+fail:


Suggested change

Py_RETURN_NONE;

fail:

Py_RETURN_NONE;

fail:

picnixz · 2025-12-30T15:57:59Z

Modules/_ssl.c

+    }
+    OSSL_ECHSTORE_free(es);
+    BIO_free_all(es_in);
+    PyBuffer_Release(ech_config);


AFAIR, there is no need for that. The caller handles it implicitly.

irl requested review from corona10, erlend-aasland, gpshead and picnixz as code owners June 12, 2025 15:58

bedevere-app bot added the awaiting review label Jun 12, 2025

bedevere-app bot mentioned this pull request Jun 12, 2025

Support TLS Encrypted ClientHello (ECH) #89730

Open

irl force-pushed the issue-89730 branch from 003ca2a to 84a0640 Compare June 12, 2025 16:10

ZeroIntensity reviewed Jun 12, 2025

View reviewed changes

Modules/_ssl.c Outdated Show resolved Hide resolved

Modules/_ssl.c Outdated Show resolved Hide resolved

Modules/_ssl.c Show resolved Hide resolved

Modules/_ssl.c Outdated Show resolved Hide resolved

ZeroIntensity added the topic-SSL label Jun 12, 2025

picnixz requested changes Jun 13, 2025

View reviewed changes

bedevere-app bot removed the awaiting review label Jun 13, 2025

bedevere-app bot added the awaiting changes label Jun 13, 2025

irl force-pushed the issue-89730 branch 2 times, most recently from 27dcb2f to 7092144 Compare June 27, 2025 13:03

irl marked this pull request as draft June 27, 2025 13:05

bedevere-app bot removed the awaiting changes label Jun 27, 2025

EncryptedClientHello support in ssl module

4fbb9cc

Exposes options for clients to use Encrypted Client Hello (ECH) when establishing TLS connections. It is up to the user to source the ECH public keys before making use of these options.

irl force-pushed the issue-89730 branch from 7092144 to 4fbb9cc Compare June 27, 2025 13:38

AdamKorcz reviewed Dec 30, 2025

View reviewed changes

Modules/_ssl.c

if (es_in == NULL) {

goto fail;

}

es = OSSL_ECHSTORE_new(NULL, NULL));

Copy link

AdamKorcz Dec 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Double closing parenthesis looks like a typo.

AdamKorcz reviewed Dec 30, 2025

View reviewed changes

Modules/_ssl.c

Py_INCREF(Py_None);

}

return retval;

fail:

Copy link

AdamKorcz Dec 30, 2025 •

edited

Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FWICS retval needs to be free'd to in fail.

AdamKorcz reviewed Dec 30, 2025

View reviewed changes

picnixz reviewed Dec 30, 2025

View reviewed changes

Uh oh!

gh-89730: EncryptedClientHello support in ssl module #135435

Are you sure you want to change the base?

gh-89730: EncryptedClientHello support in ssl module #135435

Uh oh!

Conversation

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

Uh oh!

Uh oh!

python-cla-bot bot commented Jun 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

picnixz left a comment • 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!

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!

Uh oh!

Uh oh!

Uh oh!

bedevere-app bot commented Jun 13, 2025

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!

AdamKorcz Dec 30, 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!

picnixz left a comment

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

irl commented Jun 12, 2025 •

edited by github-actions bot

Loading

python-cla-bot bot commented Jun 12, 2025 •

edited

Loading

picnixz left a comment •

edited

Loading

AdamKorcz Dec 30, 2025 •

edited

Loading