Let Codex go nuts.

Author: ZeroIntensity

Doc/library/ssl.rst

@@ -869,6 +869,40 @@ Constants
 
    .. versionadded:: 3.12
 
+.. data:: OP_ECH_GREASE
+
+   Include a GREASE ECH extension in ClientHello messages when ECH is not
+   being attempted. This can elicit an ECH retry configuration from a server.
+
+   Only available when :data:`HAS_ECH` is ``True``.
+
+   .. versionadded:: next
+
+.. data:: OP_ECH_TRIALDECRYPT
+
+   Attempt server-side ECH decryption with all available ECH keys, rather
+   than only those with a matching configuration identifier.
+
+   Only available when :data:`HAS_ECH` is ``True``.
+
+   .. versionadded:: next
+
+.. data:: OP_ECH_IGNORE_CID
+
+   Use a random ECH configuration identifier in client connections.
+
+   Only available when :data:`HAS_ECH` is ``True``.
+
+   .. versionadded:: next
+
+.. data:: OP_ECH_GREASE_RETRY_CONFIG
+
+   Include GREASE entries in the ECH retry configurations sent by a server.
+
+   Only available when :data:`HAS_ECH` is ``True``.
+
+   .. versionadded:: next
+
 .. data:: HAS_ALPN
 
    Whether the OpenSSL library has built-in support for the *Application-Layer
@@ -964,6 +998,13 @@ Constants
 
    .. versionadded:: 3.14
 
+.. data:: HAS_ECH
+
+   Whether the OpenSSL library has built-in support for Encrypted Client
+   Hello (ECH). This requires OpenSSL 4.0 or later with ECH enabled.
+
+   .. versionadded:: next
+
 .. data:: CHANNEL_BINDING_TYPES
 
    List of supported TLS channel binding types.  Strings in this list
@@ -1039,6 +1080,12 @@ Constants
 
    .. versionadded:: next
 
+.. attribute:: ECHStatus.ECH_STATUS_GREASE_ECH
+
+   The client sent a GREASE ECH extension and received a retry configuration.
+
+   .. versionadded:: next
+
 .. data:: Purpose.SERVER_AUTH
 
    Option for :func:`create_default_context` and
@@ -1377,10 +1424,13 @@ SSL sockets also have the following additional methods and attributes:
 
 .. method:: SSLSocket.get_ech_retry_config()
 
-   When the status returned by :meth:`SSLSocket.get_ech_status` after completion of the
-   handshake is :data:`ECHStatus.ECH_STATUS_GREASE_ECH`, this method returns the
-   configuration value provided by the server to be used for a new connection using
-   ECH.
+   Return the server's ECH retry configuration as :class:`bytes`, or empty
+   bytes if no retry configuration is available. When the status returned by
+   :meth:`SSLSocket.get_ech_status` after the handshake is
+   :attr:`ECHStatus.ECH_STATUS_GREASE_ECH`, the configuration can be used
+   for a new connection using ECH.
+
+   Raise :exc:`NotImplementedError` if :data:`HAS_ECH` is ``False``.
 
    .. versionadded:: next
 
@@ -1389,6 +1439,8 @@ SSL sockets also have the following additional methods and attributes:
    Gets the status of Encrypted Client Hello (ECH) processing. Returns an
    :class:`ECHStatus` instance.
 
+   Raise :exc:`NotImplementedError` if :data:`HAS_ECH` is ``False``.
+
    .. versionadded:: next
 
 .. method:: SSLSocket.selected_alpn_protocol()
@@ -1467,8 +1519,10 @@ SSL sockets also have the following additional methods and attributes:
 
    Hostname of the server name used in the outer ClientHello when Encrypted Client
    Hello (ECH) is used: :class:`str` type, or ``None`` for server-side socket or
-   if the outer server name was not specified in the constructor or the ECH
-   configuration.
+   if no outer server name is available.
+
+   Raise :exc:`NotImplementedError` if :data:`HAS_ECH` is ``False`` and the
+   socket has an SSL wrapper.
 
    .. versionadded:: next
 
@@ -1852,15 +1906,14 @@ to speed up repeated connections from the same clients.
 
    Sets an Encrypted Client Hello (ECH) configuration, which may be discovered from
    an HTTPS resource record in DNS or from :meth:`SSLSocket.get_ech_retry_config`.
-   Multiple calls to this functions will accumulate the set of values available for
-   a connection.
+   Each call replaces the context's previous configuration.
 
    If the input value provided contains no suitable value (e.g. if it only contains
    ECH configuration versions that are not supported), an :class:`SSLError` will be
    raised.
 
-   The ech_config parameter should be a bytes-like object containing the raw ECH
-   configuration.
+   The *ech_config* parameter should be a :term:`bytes-like object` containing
+   a binary-encoded ECHConfigList.
 
    This method will raise :exc:`NotImplementedError` if :data:`HAS_ECH` is ``False``.
 
@@ -1897,16 +1950,6 @@ to speed up repeated connections from the same clients.
 
    .. versionadded:: next
 
-.. method:: SSLContext.set_outer_server_hostname(server_hostname)
-
-   Specify which hostname the socket should advertise during the TLS
-   handshake in the outer ClientHello when ECH is used.
-
-   This method will raise :exc:`NotImplementedError` if :data:`HAS_ECH` is
-   ``False``.
-
-   .. versionadded:: next
-
 .. attribute:: SSLContext.sni_callback
 
    Register a callback function that will be called after the TLS Client Hello
@@ -3051,50 +3094,61 @@ of TLS/SSL. Some new TLS 1.3 features are not yet available.
 - TLS 1.3 features like early data, deferred TLS client cert request,
   and rekeying are not supported yet.
 
+.. _ssl-encrypted-client-hello:
+
 Encrypted Client Hello
 ^^^^^^^^^^^^^^^^^^^^^^
 
 .. versionadded:: next
 
-Encrypted Client Hello (ECH) allows for encrypting values that have previously only been
-included unencrypted in the ClientHello records when establishing a TLS connection. To use
-ECH it is necessary to provide configuration values that contain a version, algorithm
-parameters, the public key to use for HPKE encryption and the "public_name" that is by
-default used for the unencrypted (outer) SNI when ECH is attempted. These configuration
-values may be discovered through DNS or through the "retry config" mechanism.
+Encrypted Client Hello (ECH) encrypts values in the ClientHello record sent when
+establishing a TLS connection. It requires an ECHConfigList containing algorithm
+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.
 
-The following example assumes that you have discovered a set of ECH configuration values
-from DNS, or *ech_configs* may be an empty list to rely on the "retry config" mechanism::
+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
+GREASE to request a retry configuration from the server::
 
     import socket
     import ssl
 
 
-    def connect_with_tls_ech(hostname: str, ech_configs: List[str],
-                         use_retry_config: bool=True) -> ssl.SSLSocket:
+    def connect_with_tls_ech(hostname, ech_config=None, use_retry_config=True):
         context = ssl.create_default_context()
-        for ech_config in ech_configs:
+        if ech_config is not None:
             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
-                        and use_retry_config):
-                    return connect_with_ech(hostname, [ssock.get_ech_retry_config()],
-                                            False)
-                return ssock
+        else:
+            context.options |= ssl.OP_ECH_GREASE
+        sock = socket.create_connection((hostname, 443))
+        try:
+            ssock = context.wrap_socket(sock, server_hostname=hostname)
+        except BaseException:
+            sock.close()
+            raise
+        if (use_retry_config
+                and ssock.get_ech_status()
+                == ssl.ECHStatus.ECH_STATUS_GREASE_ECH):
+            try:
+                retry_config = ssock.get_ech_retry_config()
+            finally:
+                ssock.close()
+            return connect_with_tls_ech(hostname, retry_config, False)
+        return ssock
 
     hostname = "www.python.org"
-    ech_configs = []  # Replace with a call to a function to lookup
-                      # ECH configurations in DNS
+    ech_config = None  # Replace with an ECHConfigList discovered through DNS.
 
-    ssock = connect_with_tls_ech(hostname, ech_configs)
+    with connect_with_tls_ech(hostname, ech_config) as ssock:
+        print(ssock.get_ech_status())
 
 The following classes, methods, and attributes will be useful for using ECH:
 
  - :class:`ECHStatus`
  - :meth:`SSLContext.set_ech_config`
  - :meth:`SSLContext.set_outer_alpn_protocols`
- - :meth:`SSLContext.set_outer_server_hostname`
  - :meth:`SSLSocket.get_ech_status`
  - :meth:`SSLSocket.get_ech_retry_config`
 

Doc/whatsnew/3.16.rst

@@ -688,6 +688,18 @@ sqlite3
 ssl
 ---
 
+* Added support for :ref:`Encrypted Client Hello <ssl-encrypted-client-hello>`
+  (ECH) with OpenSSL 4.0 or later. Clients can use
+  :meth:`~ssl.SSLContext.set_ech_config` to supply an ECHConfigList discovered
+  through DNS, for example using a third-party library such as ``dnspython``
+  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.
+  :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.
+  (Contributed by Iain R. Learmonth and Peter Bierma in :gh:`89730`.)
+
 * :const:`ssl.OPENSSL_VERSION_INFO` is now a named tuple.
   Added :const:`~ssl.OPENSSL_API_VERSION_INFO` which provides information
   about the version of the OpenSSL library that was used for building

Lib/ssl.py

@@ -116,7 +116,8 @@
 
 from _ssl import (
     HAS_SNI, HAS_ECDH, HAS_NPN, HAS_ALPN, HAS_SSLv2, HAS_SSLv3, HAS_TLSv1,
-    HAS_TLSv1_1, HAS_TLSv1_2, HAS_TLSv1_3, HAS_PSK, HAS_PSK_TLS13, HAS_PHA
+    HAS_TLSv1_1, HAS_TLSv1_2, HAS_TLSv1_3, HAS_PSK, HAS_PSK_TLS13, HAS_PHA,
+    HAS_ECH
 )
 from _ssl import _DEFAULT_CIPHERS, _OPENSSL_API_VERSION
 
@@ -522,11 +523,11 @@ def shim_cb(sslobj, servername, sslctx):
             self.sni_callback = shim_cb
 
     def set_alpn_protocols(self, alpn_protocols):
-        protos = encode_alpn_protocol_list(alpn_protocols)
+        protos = _encode_alpn_protocol_list(alpn_protocols)
         self._set_alpn_protocols(protos)
 
     def set_outer_alpn_protocols(self, alpn_protocols):
-        protos = encode_alpn_protocol_list(alpn_protocols)
+        protos = _encode_alpn_protocol_list(alpn_protocols)
         self._set_outer_alpn_protocols(protos)
 
     def _load_windows_store_certs(self, storename, purpose):
@@ -1003,8 +1004,13 @@ def verify_client_post_handshake(self):
         return self._sslobj.verify_client_post_handshake()
 
     def get_ech_status(self):
+        """Return the status of Encrypted Client Hello processing."""
         return ECHStatus(self._sslobj.get_ech_status()[0])
 
+    def get_ech_retry_config(self):
+        """Return the server's ECH retry configuration as bytes."""
+        return self._sslobj.get_ech_retry_config()
+
 
 def _sslcopydoc(func):
     """Copy docstring from SSLObject to SSLSocket"""
@@ -1031,14 +1037,11 @@ def __init__(self, *args, **kwargs):
     @classmethod
     def _create(cls, sock, server_side=False, do_handshake_on_connect=True,
                 suppress_ragged_eofs=True, server_hostname=None,
-                context=None, session=None, outer_server_hostname=None):
+                context=None, session=None):
         if sock.getsockopt(SOL_SOCKET, SO_TYPE) != SOCK_STREAM:
             raise NotImplementedError("only stream sockets are supported")
         _check_sslobject_params(server_side=server_side, context=context,
                                 server_hostname=server_hostname, session=session)
-        if server_side and outer_server_hostname:
-            raise ValueError("outer_server_hostname can only be specified "
-                             "in client mode")
 
         sock_timeout = sock.gettimeout()
         kwargs = dict(
@@ -1137,7 +1140,8 @@ def context(self, ctx):
     @property
     def outer_server_hostname(self):
         """The server name used in the outer ClientHello."""
-        return self._sslobj.get_ech_status()[2]
+        if self._sslobj is not None:
+            return self._sslobj.get_ech_status()[2]
 
     @property
     @_sslcopydoc
@@ -1440,8 +1444,15 @@ def verify_client_post_handshake(self):
         else:
             raise ValueError("No SSL wrapper around " + str(self))
 
+    @_sslcopydoc
     def get_ech_status(self):
-        return ECHStatus(self._sslobj.get_ech_status()[0])
+        if self._sslobj is not None:
+            return ECHStatus(self._sslobj.get_ech_status()[0])
+
+    @_sslcopydoc
+    def get_ech_retry_config(self):
+        if self._sslobj is not None:
+            return self._sslobj.get_ech_retry_config()
 
     def _real_close(self):
         self._sslobj = None
@@ -1610,7 +1621,8 @@ def get_server_certificate(addr, ssl_version=PROTOCOL_TLS_CLIENT,
 def get_protocol_name(protocol_code):
     return _PROTOCOL_NAMES.get(protocol_code, '<unknown>')
 
-def encode_alpn_protocol_list(alpn_protocols):
+
+def _encode_alpn_protocol_list(alpn_protocols):
     protos = bytearray()
     for protocol in alpn_protocols:
         b = bytes(protocol, 'ascii')