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.

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.

ZeroIntensity · 2025-06-12T17:30:59Z

Modules/_ssl.c

+	PyObject *retval = PyTuple_New(3);
+    PyTuple_SetItem(retval, 0, PyLong_FromLong(status));


PyTuple_New can fail, and use PyTuple_SET_ITEM to avoid error checking there.

ZeroIntensity · 2025-06-12T17:31:09Z

Modules/_ssl.c

+    PyTuple_SetItem(retval, 0, PyLong_FromLong(status));
+
+    if (inner_sni != NULL) {
+        PyTuple_SetItem(retval, 1, PyUnicode_FromString(inner_sni));


PyUnicode_FromString can fail.

ZeroIntensity · 2025-06-12T17:32:08Z

Modules/_ssl.c

@@ -2073,6 +2077,111 @@ cipher_to_dict(const SSL_CIPHER *cipher)
       );
 }

+/*[clinic input]


I'm pretty sure you need to decorate these with @critical_section for free-threading.

ZeroIntensity · 2025-06-12T17:32:18Z

Modules/_ssl.c

@@ -70,6 +70,10 @@
 #include "openssl/bio.h"
 #include "openssl/dh.h"

+#if __has_include("openssl/ech.h")


Check #ifdef __has_include.

Also use the macro OPENSSL_ECH that you defined (which should be renamed)

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

picnixz · 2025-06-13T14:59:41Z

Doc/library/ssl.rst

@@ -214,7 +214,6 @@ purposes.
      The context now uses :data:`VERIFY_X509_PARTIAL_CHAIN` and
      :data:`VERIFY_X509_STRICT` in its default verify flags.

-


Keep this line.

picnixz · 2025-06-13T14:59:47Z

Doc/library/ssl.rst

+   :class:`enum.IntEnum` collection of Encrypted Client Hello (ECH) statuses
+   returned by :meth:`SSLSocket.get_ech_status`.
+
+   .. versionadded:: TODO XXX


Suggested change

.. versionadded:: TODO XXX

.. versionadded:: next

And ditto for the rest

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.

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

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

@@ -0,0 +1,8 @@
+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


Suggested change

libraries like dnspython can be used to query for HTTPS and SVCB records

libraries like ``dnspython`` can be used to query for HTTPS and SVCB records

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

Modules/_ssl.c

@@ -70,6 +70,10 @@
 #include "openssl/bio.h"
 #include "openssl/dh.h"

+#if __has_include("openssl/ech.h")


Also use the macro OPENSSL_ECH that you defined (which should be renamed)

picnixz · 2025-06-13T16:38:08Z

Modules/_ssl.c

+    if ((es_in = BIO_new_mem_buf(ech_config->buf, ech_config->len)) == NULL
+        || (es = OSSL_ECHSTORE_new(NULL, NULL)) == NULL
+        || OSSL_ECHSTORE_read_echconfiglist(es, es_in) != 1
+        || SSL_CTX_set1_echstore(self->ctx, es) != 1) {
+        _setSSLError(get_state_ctx(self), NULL, 0, __FILE__, __LINE__);


Break down this big if into multiple ones and use a goto error with an error label doing the cleanup.

picnixz · 2025-06-13T16:41:09Z

Lib/ssl.py

@@ -459,7 +464,7 @@ def wrap_socket(self, sock, server_side=False,
            suppress_ragged_eofs=suppress_ragged_eofs,
            server_hostname=server_hostname,
            context=self,
-            session=session
+            session=session,


Revert this change, it's not needed.

picnixz · 2025-06-13T16:42:36Z

Lib/ssl.py

+    @property
+    def outer_server_hostname(self) -> str:
+        """The server name used in the outer ClientHello."""
+        if self._sslobj:
+            return self._sslobj.get_ech_status()[2]
+        else:
+            raise ValueError("No SSL wrapper around " + str(self))


Suggested change

@property

def outer_server_hostname(self) -> str:

"""The server name used in the outer ClientHello."""

if self._sslobj:

return self._sslobj.get_ech_status()[2]

else:

raise ValueError("No SSL wrapper around " + str(self))

@property

def outer_server_hostname(self):

"""The server name used in the outer ClientHello."""

return self._sslobj.get_ech_status()[2]

We don't use type annotations in the standard library, it's left to typeshed. And let's just propagate an AttributeError as for the other properties.

picnixz · 2025-06-13T16:44:03Z

Lib/ssl.py

+    def outer_server_hostname(self) -> str:
+        """The server name used in the outer ClientHello."""
+        if self._sslobj:
+            return self._sslobj.get_ech_status()[2]
+        else:
+            raise ValueError("No SSL wrapper around " + str(self))


Suggested change

def outer_server_hostname(self) -> str:

"""The server name used in the outer ClientHello."""

if self._sslobj:

return self._sslobj.get_ech_status()[2]

else:

raise ValueError("No SSL wrapper around " + str(self))

def outer_server_hostname(self):

"""The server name used in the outer ClientHello."""

if self._sslobj:

return self._sslobj.get_ech_status()[2]

Other properties actually return None if sslobj is None.

picnixz · 2025-06-13T16:45:33Z

Lib/ssl.py

+    protos = bytearray()
+    for protocol in alpn_protocols:
+        b = bytes(protocol, 'ascii')
+        if len(b) == 0 or len(b) > 255:


Suggested change

if len(b) == 0 or len(b) > 255:

if not b or len(b) > 255:

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.

irl requested review from gpshead, picnixz, erlend-aasland and corona10 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

EncryptedClientHello support in ssl module

84a0640

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 003ca2a to 84a0640 Compare June 12, 2025 16:10

ZeroIntensity reviewed Jun 12, 2025

View reviewed changes

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

		PyObject *retval = PyTuple_New(3);
		PyTuple_SetItem(retval, 0, PyLong_FromLong(status));

		@@ -214,7 +214,6 @@ purposes.
		The context now uses :data:`VERIFY_X509_PARTIAL_CHAIN` and
		:data:`VERIFY_X509_STRICT` in its default verify flags.

	libraries like dnspython can be used to query for HTTPS and SVCB records
	libraries like ``dnspython`` can be used to query for HTTPS and SVCB records

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!

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 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!

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!

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!

bedevere-app bot commented Jun 13, 2025

Uh oh!

Uh oh!

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