Implement support for ECH servers.

Author: ZeroIntensity

Doc/library/ssl.rst

@@ -1709,6 +1709,29 @@ to speed up repeated connections from the same clients.
 
    .. versionadded:: 3.4
 
+.. method:: SSLContext.load_ech_keys(keyfile, *, for_retry=True)
+
+   Load a server's Encrypted Client Hello (ECH) private key and configuration.
+   The *keyfile* must be the path to a PEM file containing an unencrypted
+   private key followed by its matching ECHConfigList. Load the server's TLS
+   certificate and private key separately with :meth:`load_cert_chain`.
+
+   Each call adds keys and configurations to those already loaded into the
+   context. If *for_retry* is true, the new configurations are included in
+   ECH retry configurations sent to clients.
+
+   Configure ECH keys on the initial server context before accepting
+   connections. After successful ECH decryption, :attr:`sni_callback`
+   receives the inner server name.
+
+   Invalid or missing keys or configurations, or a key that does not match
+   its configuration, raise :exc:`SSLError`. File access errors raise
+   :exc:`OSError`.
+
+   Only available when :data:`HAS_ECH` is ``True``.
+
+   .. versionadded:: next
+
 .. method:: SSLContext.load_verify_locations(cafile=None, capath=None, cadata=None)
 
    Load a set of "certification authority" (CA) certificates used to validate
@@ -3107,6 +3130,10 @@ parameters, a public key, and a public name used in the unencrypted outer
 ClientHello. ECH requires OpenSSL 4.0 or later with ECH enabled; check
 :data:`HAS_ECH` before using it.
 
+Servers can load a PEM file containing their ECH private key and configuration
+with :meth:`SSLContext.load_ech_keys`. Clients use the corresponding public
+ECHConfigList with :meth:`SSLContext.set_ech_config`.
+
 Configuration values may be discovered through DNS or through the server's
 retry configuration. The following example accepts a binary-encoded
 ECHConfigList discovered through DNS. If none is supplied, it enables ECH
@@ -3147,6 +3174,7 @@ GREASE to request a retry configuration from the server::
 The following classes, methods, and attributes will be useful for using ECH:
 
  - :class:`ECHStatus`
+ - :meth:`SSLContext.load_ech_keys`
  - :meth:`SSLContext.set_ech_config`
  - :meth:`SSLContext.set_outer_alpn_protocols`
  - :meth:`SSLSocket.get_ech_status`

Doc/whatsnew/3.16.rst

@@ -695,6 +695,8 @@ ssl
   to query HTTPS or SVCB records. Clients can also enable
   :data:`~ssl.OP_ECH_GREASE` and retrieve a server's retry configuration
   with :meth:`~ssl.SSLSocket.get_ech_retry_config` for a subsequent connection.
+  Servers can use :meth:`~ssl.SSLContext.load_ech_keys` to load ECH private
+  keys and their configurations from PEM files.
   :data:`~ssl.HAS_ECH` indicates whether ECH is available, and
   :meth:`~ssl.SSLSocket.get_ech_status` reports the status as an
   :class:`~ssl.ECHStatus` member.

Include/internal/pycore_global_objects_fini_generated.h

@@ -513,6 +513,7 @@ struct _Py_global_strings {
         STRUCT_FOR_ID(fold)
         STRUCT_FOR_ID(foldspaces)
         STRUCT_FOR_ID(follow_symlinks)
+        STRUCT_FOR_ID(for_retry)
         STRUCT_FOR_ID(format)
         STRUCT_FOR_ID(format_spec)
         STRUCT_FOR_ID(frame_buffer)

Include/internal/pycore_global_strings.h

@@ -14,6 +14,7 @@
 from test.support import warnings_helper
 from test.support import asyncore
 import array
+import base64
 import re
 import socket
 import select
@@ -2071,7 +2072,8 @@ def test_availability(self):
             with self.subTest(module=module):
                 self.assertEqual(bool(names), ssl.HAS_ECH)
 
-        context_methods = ('set_ech_config', '_set_outer_alpn_protocols')
+        context_methods = ('set_ech_config', 'load_ech_keys',
+                           '_set_outer_alpn_protocols')
         socket_methods = ('get_ech_status', 'get_ech_retry_config')
         for owner, names in (
             (_ssl._SSLContext, context_methods),
@@ -2123,6 +2125,95 @@ def test_mixed_ech_config_versions(self):
             config = len(entries).to_bytes(2, 'big') + entries
             self.assertIsNone(ctx.set_ech_config(config))
 
+    def read_ech_key_and_config(self):
+        # Generated with:
+        # openssl ech -public_name public.example -suite 0x20,1,1
+        with open(data_file('ech.pem'), 'rb') as f:
+            key, config = f.read().split(b'-----BEGIN ECHCONFIG-----')
+        config = base64.b64decode(config.split(b'-----END ECHCONFIG-----')[0])
+        return key, config
+
+    @unittest.skipUnless(ssl.HAS_ECH, 'requires ECH')
+    def test_load_ech_keys(self):
+        client_ctx, ctx, hostname = testing_context()
+        filename = data_file('ech.pem')
+        for path in (filename, os.fsencode(filename),
+                     os_helper.FakePath(filename)):
+            self.assertIsNone(ctx.load_ech_keys(path))
+        self.assertRaises(TypeError, ctx.load_ech_keys, None)
+        self.assertRaises(ValueError, ctx.load_ech_keys, 'key\x00file')
+        with self.assertRaises(OSError) as cm:
+            ctx.load_ech_keys(NONEXISTINGKEY)
+        self.assertEqual(cm.exception.errno, errno.ENOENT)
+        self.assertEqual(cm.exception.filename, NONEXISTINGKEY)
+
+        key, config = self.read_ech_key_and_config()
+        public = (b'-----BEGIN ECHCONFIG-----\n' + base64.b64encode(config)
+                  + b'\n-----END ECHCONFIG-----\n')
+        mismatched = bytearray(config)
+        mismatched[11] ^= 1  # Change one bit of the HPKE public key.
+        mismatched = (key + b'-----BEGIN ECHCONFIG-----\n'
+                      + base64.b64encode(mismatched)
+                      + b'\n-----END ECHCONFIG-----\n')
+        with open(ONLYKEY_PROTECTED, 'rb') as f:
+            encrypted = f.read() + public
+        self.addCleanup(os_helper.unlink, os_helper.TESTFN)
+        for pem in (b'invalid', public, mismatched, encrypted):
+            with self.subTest(pem=pem):
+                with open(os_helper.TESTFN, 'wb') as f:
+                    f.write(pem)
+                self.assertRaises(ssl.SSLError, ctx.load_ech_keys,
+                                  os_helper.TESTFN)
+        # Failed loads must leave the previously loaded keys usable.
+        client_ctx.minimum_version = ssl.TLSVersion.TLSv1_3
+        client_ctx.set_ech_config(config)
+        client, server, *_ = connected_bio_pair(client_ctx, ctx, hostname)
+        self.assertEqual(client.get_ech_status(),
+                         ssl.ECHStatus.ECH_STATUS_SUCCESS)
+
+    @unittest.skipUnless(ssl.HAS_ECH, 'requires ECH')
+    def test_ech_handshake(self):
+        key, config = self.read_ech_key_and_config()
+        other_config = bytearray(config)
+        other_config[6] ^= 1  # A different config_id using the same key.
+        self.addCleanup(os_helper.unlink, os_helper.TESTFN)
+        with open(os_helper.TESTFN, 'wb') as f:
+            f.write(key + b'-----BEGIN ECHCONFIG-----\n'
+                    + base64.b64encode(other_config)
+                    + b'\n-----END ECHCONFIG-----\n')
+        client_ctx, server_ctx, hostname = testing_context()
+        client_ctx.minimum_version = ssl.TLSVersion.TLSv1_3
+        server_ctx.load_ech_keys(data_file('ech.pem'), for_retry=False)
+        server_ctx.load_ech_keys(os_helper.TESTFN)
+        # Both the old and newly appended configurations must work.
+        for current_config in (config, other_config):
+            with self.subTest(config_id=current_config[6]):
+                client_ctx.set_ech_config(current_config)
+                seen_names = []
+
+                def sni_callback(obj, name, ctx):
+                    seen_names.append(name)
+
+                server_ctx.sni_callback = sni_callback
+                client, server, c_in, c_out, s_in, s_out = connected_bio_pair(
+                    client_ctx, server_ctx, hostname)
+                for obj in (client, server):
+                    self.assertEqual(obj.get_ech_status(),
+                                     ssl.ECHStatus.ECH_STATUS_SUCCESS)
+                    self.assertEqual(obj.outer_server_hostname,
+                                     'public.example')
+                self.assertEqual(seen_names, [hostname])
+                client.write(b'hello')
+                s_in.write(c_out.read())
+                self.assertEqual(server.read(), b'hello')
+                server.write(b'world')
+                c_in.write(s_out.read())
+                self.assertEqual(client.read(), b'world')
+        client_ctx, _, hostname = testing_context()
+        client_ctx.options |= ssl.OP_ECH_GREASE
+        client, server, *_ = connected_bio_pair(client_ctx, server_ctx, hostname)
+        self.assertEqual(client.get_ech_retry_config(), bytes(other_config))
+
     @unittest.skipUnless(ssl.HAS_ECH, 'requires ECH')
     def test_status_before_handshake(self):
         ctx = make_test_context()

Include/internal/pycore_runtime_init_generated.h

@@ -1,3 +1,2 @@
-Add client support for Encrypted Client Hello (ECH) to the :mod:`ssl` module
-with OpenSSL 4.0 or later. ECH configurations can be supplied with
-:meth:`ssl.SSLContext.set_ech_config`.
+Add support for Encrypted Client Hello (ECH) to the :mod:`ssl` module with
+OpenSSL 4.0 or later.

Include/internal/pycore_unicodeobject_generated.h

@@ -5273,7 +5273,10 @@ _ssl__SSLContext_set_ech_config_impl(PySSLContext *self,
     if (OSSL_ECHSTORE_read_echconfiglist(store, config_bio) != 1) {
         goto fail;
     }
-    if (SSL_CTX_set1_echstore(self->ctx, store) != 1) {
+    PyMutex_Lock(&self->tstate_mutex);
+    int result = SSL_CTX_set1_echstore(self->ctx, store);
+    PyMutex_Unlock(&self->tstate_mutex);
+    if (result != 1) {
         goto fail;
     }
     OSSL_ECHSTORE_free(store);
@@ -5286,6 +5289,109 @@ _ssl__SSLContext_set_ech_config_impl(PySSLContext *self,
     BIO_free(config_bio);
     return NULL;
 }
+
+static int
+ech_password_callback(char *buf, int size, int rwflag, void *userdata)
+{
+    /* ECH key files must be unencrypted. Never prompt for a password. */
+    return -1;
+}
+
+static int
+load_ech_keys(SSL_CTX *ctx, BIO *bio, int for_retry)
+{
+    int result = 0;
+    int old_keys, new_keys;
+    OSSL_ECHSTORE *store = NULL;
+    EVP_PKEY *key = PEM_read_bio_PrivateKey(bio, NULL,
+                                           ech_password_callback, NULL);
+    if (key == NULL) {
+        goto end;
+    }
+    store = SSL_CTX_get1_echstore(ctx);
+    if (store == NULL) {
+        if (ERR_peek_error() != 0) {
+            goto end;
+        }
+        store = OSSL_ECHSTORE_new(NULL, NULL);
+        if (store == NULL) {
+            goto end;
+        }
+    }
+    if (OSSL_ECHSTORE_num_keys(store, &old_keys) != 1 ||
+        OSSL_ECHSTORE_set1_key_and_read_pem(store, key, bio, for_retry) != 1 ||
+        OSSL_ECHSTORE_num_keys(store, &new_keys) != 1) {
+        goto end;
+    }
+    /* OpenSSL may match a key already in the store. Require a new match. */
+    if (new_keys <= old_keys) {
+        ERR_raise(ERR_LIB_SSL, SSL_R_PRIVATE_KEY_MISMATCH);
+        goto end;
+    }
+    result = SSL_CTX_set1_echstore(ctx, store);
+
+end:
+    EVP_PKEY_free(key);
+    OSSL_ECHSTORE_free(store);
+    return result;
+}
+
+/*[clinic input]
+@critical_section
+_ssl._SSLContext.load_ech_keys
+
+    keyfile: object
+    *
+    for_retry: bool = True
+
+Load server ECH keys and configurations from a PEM file.
+
+The file must contain an unencrypted private key followed by its
+ECHConfigList.
+If for_retry is true, advertise the configurations in ECH retry
+responses.
+[clinic start generated code]*/
+
+static PyObject *
+_ssl__SSLContext_load_ech_keys_impl(PySSLContext *self, PyObject *keyfile,
+                                    int for_retry)
+/*[clinic end generated code: output=8de2cc58ce2f8077 input=3e6617d346227acd]*/
+{
+    PyObject *keyfile_bytes;
+    if (!PyUnicode_FSConverter(keyfile, &keyfile_bytes)) {
+        return NULL;
+    }
+    const char *filename = PyBytes_AS_STRING(keyfile_bytes);
+    int result = 0;
+    int open_failed = 0;
+
+    ERR_clear_error();
+    PySSL_BEGIN_ALLOW_THREADS(self)
+    errno = 0;
+    BIO *bio = BIO_new_file(filename, "rb");
+    if (bio == NULL) {
+        open_failed = 1;
+    }
+    else {
+        result = load_ech_keys(self->ctx, bio, for_retry);
+        BIO_free(bio);
+    }
+    PySSL_END_ALLOW_THREADS(self)
+
+    if (result != 1) {
+        if (open_failed && errno != 0) {
+            PyErr_SetFromErrnoWithFilenameObject(PyExc_OSError, keyfile);
+            ERR_clear_error();
+        }
+        else {
+            _setSSLError(get_state_ctx(self), NULL, 0, __FILE__, __LINE__);
+        }
+        Py_DECREF(keyfile_bytes);
+        return NULL;
+    }
+    Py_DECREF(keyfile_bytes);
+    Py_RETURN_NONE;
+}
 #endif /* HAVE_OPENSSL_ECH */
 
 /*[clinic input]
@@ -5968,6 +6074,7 @@ static struct PyMethodDef context_methods[] = {
     _SSL__SSLCONTEXT_SET_DEFAULT_VERIFY_PATHS_METHODDEF
     _SSL__SSLCONTEXT_SET_ECDH_CURVE_METHODDEF
     _SSL__SSLCONTEXT_SET_ECH_CONFIG_METHODDEF
+    _SSL__SSLCONTEXT_LOAD_ECH_KEYS_METHODDEF
     _SSL__SSLCONTEXT__SET_OUTER_ALPN_PROTOCOLS_METHODDEF
     _SSL__SSLCONTEXT_CERT_STORE_STATS_METHODDEF
     _SSL__SSLCONTEXT_GET_CA_CERTS_METHODDEF