Per-socket ECH config.

Author: ZeroIntensity

Doc/library/ssl.rst

@@ -321,6 +321,23 @@ Exceptions
 
       A human readable string of the verification error.
 
+.. exception:: SSLECHRejectedError
+
+   A subclass of :exc:`SSLError` raised when the handshake fails because the
+   server rejected :ref:`Encrypted Client Hello <ssl-encrypted-client-hello>`.
+   The connection cannot be used. If :attr:`retry_config` is not empty, the
+   client may retry once with a new connection using that configuration.
+
+   This exception is only raised when :data:`HAS_ECH` is ``True``.
+
+   .. attribute:: retry_config
+
+      The server's ECH retry configuration as a binary-encoded ECHConfigList,
+      or empty :class:`bytes` if the server did not provide one or the server
+      could not be authenticated under the outer server name.
+
+   .. versionadded:: next
+
 .. exception:: CertificateError
 
    An alias for :exc:`SSLCertVerificationError`.
@@ -1430,7 +1447,10 @@ SSL sockets also have the following additional methods and attributes:
    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.
+   for a new connection using ECH. When the server rejects a real ECH
+   attempt, the handshake raises :exc:`SSLECHRejectedError`, which carries
+   the same configuration in its :attr:`~SSLECHRejectedError.retry_config`
+   attribute.
 
    Only available when :data:`HAS_ECH` is ``True``.
 
@@ -1445,6 +1465,26 @@ SSL sockets also have the following additional methods and attributes:
 
    .. versionadded:: next
 
+.. method:: SSLSocket.set_ech_config(ech_config)
+
+   Set the Encrypted Client Hello (ECH) configuration for this connection
+   only, replacing any configuration set on the context with
+   :meth:`SSLContext.set_ech_config`. The *ech_config* parameter accepts the
+   same values. Unlike the context's configuration, which applies to every
+   connection made from it, a connection's configuration is only used by that
+   connection and can therefore be chosen per destination host, which is how
+   ECH configurations are published in DNS.
+
+   The configuration must be set before the handshake starts, so this is
+   mostly useful with ``do_handshake_on_connect=False`` or on a socket that
+   is not connected yet. :meth:`SSLContext.wrap_socket` and
+   :meth:`SSLContext.wrap_bio` accept the configuration as their *ech_config*
+   argument instead.
+
+   Only available when :data:`HAS_ECH` is ``True``.
+
+   .. versionadded:: next
+
 .. method:: SSLSocket.selected_alpn_protocol()
 
    Return the protocol that was selected during the TLS handshake.  If
@@ -1932,6 +1972,14 @@ to speed up repeated connections from the same clients.
    an HTTPS resource record in DNS or from :meth:`SSLSocket.get_ech_retry_config`.
    Each call replaces the context's previous configuration.
 
+   The configuration applies to every connection made from the context, and a
+   server that cannot decrypt it rejects the connection with
+   :exc:`SSLECHRejectedError`. Because ECH configurations are published per
+   host, a context with a configuration should only be used for connections to
+   the hosts that publish it. To use a configuration for a single connection,
+   pass it as the *ech_config* argument of :meth:`wrap_socket` or
+   :meth:`wrap_bio` instead.
+
    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.
@@ -2080,7 +2128,7 @@ to speed up repeated connections from the same clients.
 
 .. method:: SSLContext.wrap_socket(sock, server_side=False, \
       do_handshake_on_connect=True, suppress_ragged_eofs=True, \
-      server_hostname=None, session=None)
+      server_hostname=None, session=None, ech_config=None)
 
    Wrap an existing Python socket *sock* and return an instance of
    :attr:`SSLContext.sslsocket_class` (default :class:`SSLSocket`). The
@@ -2121,6 +2169,10 @@ to speed up repeated connections from the same clients.
 
    *session*, see :attr:`~SSLSocket.session`.
 
+   *ech_config*, see :meth:`SSLSocket.set_ech_config`. Specifying
+   *ech_config* will raise a :exc:`ValueError` if *server_side* is true, and
+   a :exc:`NotImplementedError` if :data:`HAS_ECH` is ``False``.
+
    To wrap an :class:`SSLSocket` in another :class:`SSLSocket`, use
    :meth:`SSLContext.wrap_bio`.
 
@@ -2135,6 +2187,9 @@ to speed up repeated connections from the same clients.
       The method returns an instance of :attr:`SSLContext.sslsocket_class`
       instead of hard-coded :class:`SSLSocket`.
 
+   .. versionchanged:: next
+      *ech_config* argument was added.
+
 .. attribute:: SSLContext.sslsocket_class
 
    The return type of :meth:`SSLContext.wrap_socket`, defaults to
@@ -2145,16 +2200,17 @@ to speed up repeated connections from the same clients.
    .. versionadded:: 3.7
 
 .. method:: SSLContext.wrap_bio(incoming, outgoing, server_side=False, \
-                                server_hostname=None, session=None)
+                                server_hostname=None, session=None, \
+                                ech_config=None)
 
    Wrap the BIO objects *incoming* and *outgoing* and return an instance of
    :attr:`SSLContext.sslobject_class` (default :class:`SSLObject`). The SSL
    routines will read input data from the incoming BIO and write data to the
    outgoing BIO.
 
-   The *server_side*, *server_hostname* and *session* parameters have the
-   same meaning as in :meth:`SSLContext.wrap_socket`, and are validated in
-   the same way: in particular a :exc:`ValueError` is raised when
+   The *server_side*, *server_hostname*, *session* and *ech_config*
+   parameters have the same meaning as in :meth:`SSLContext.wrap_socket`,
+   and are validated in the same way: in particular a :exc:`ValueError` is raised when
    :attr:`~SSLContext.check_hostname` is enabled but no *server_hostname* is
    given, since there would be no name to match the peer's certificate
    against.
@@ -2173,6 +2229,9 @@ to speed up repeated connections from the same clients.
       *server_hostname* was accepted, and verified the certificate chain but
       never the peer's identity.
 
+   .. versionchanged:: next
+      *ech_config* argument was added.
+
 .. attribute:: SSLContext.sslobject_class
 
    The return type of :meth:`SSLContext.wrap_bio`, defaults to
@@ -2891,6 +2950,7 @@ provided.
    - :meth:`~SSLSocket.verify_client_post_handshake`
    - :meth:`~SSLSocket.unwrap`
    - :meth:`~SSLSocket.get_channel_binding`
+   - :meth:`~SSLSocket.set_ech_config`
    - :meth:`~SSLSocket.get_ech_retry_config`
    - :meth:`~SSLSocket.get_ech_status`
    - :meth:`~SSLSocket.version`
@@ -3132,51 +3192,51 @@ ClientHello. ECH requires OpenSSL 4.0 or later with ECH enabled; check
 
 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`.
+ECHConfigList, published in DNS for each host, as the *ech_config* argument of
+:meth:`SSLContext.wrap_socket` or :meth:`SSLContext.wrap_bio`, or for every
+connection from a context 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
-GREASE to request a retry configuration from the server::
+A server that has rotated its ECH keys rejects the connection and provides a
+retry configuration, which the handshake raises as
+:exc:`SSLECHRejectedError`. The following example accepts a binary-encoded
+ECHConfigList discovered through DNS and retries once with the server's retry
+configuration. If no configuration is supplied, it enables ECH GREASE, which a
+server may answer with a retry configuration for a later connection::
 
     import socket
     import ssl
 
 
-    def connect_with_tls_ech(hostname, ech_config=None, use_retry_config=True):
+    def connect_with_tls_ech(hostname, ech_config=None, retry=True):
         context = ssl.create_default_context()
-        if ech_config is not None:
-            context.set_ech_config(ech_config)
-        else:
+        if ech_config is None:
             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()
+            return context.wrap_socket(sock, server_hostname=hostname,
+                                       ech_config=ech_config)
+        except ssl.SSLECHRejectedError as exc:
+            if retry and exc.retry_config:
+                return connect_with_tls_ech(hostname, exc.retry_config,
+                                            retry=False)
             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_config = None  # Replace with an ECHConfigList discovered through DNS.
 
     with connect_with_tls_ech(hostname, ech_config) as ssock:
         print(ssock.get_ech_status())
+        if ssock.get_ech_status() == ssl.ECHStatus.ECH_STATUS_GREASE_ECH:
+            print("retry configuration:", ssock.get_ech_retry_config())
 
 The following classes, methods, and attributes will be useful for using ECH:
 
  - :class:`ECHStatus`
+ - :exc:`SSLECHRejectedError`
  - :meth:`SSLContext.load_ech_keys`
  - :meth:`SSLContext.set_ech_config`
  - :meth:`SSLContext.set_outer_alpn_protocols`
+ - :meth:`SSLSocket.set_ech_config`
  - :meth:`SSLSocket.get_ech_status`
  - :meth:`SSLSocket.get_ech_retry_config`
 

Doc/whatsnew/3.16.rst

@@ -689,12 +689,15 @@ 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.
+  (ECH) with OpenSSL 4.0 or later. Clients can supply an ECHConfigList
+  discovered through DNS, for example using a third-party library such as
+  ``dnspython`` to query HTTPS or SVCB records, as the *ech_config* argument
+  of :meth:`~ssl.SSLContext.wrap_socket` and :meth:`~ssl.SSLContext.wrap_bio`
+  or with :meth:`~ssl.SSLContext.set_ech_config`. A rejected ECH attempt
+  raises :exc:`~ssl.SSLECHRejectedError`, which carries the server's retry
+  configuration. 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

Lib/ssl.py

@@ -107,7 +107,8 @@
 from _ssl import _SSLContext, MemoryBIO, SSLSession
 from _ssl import (
     SSLError, SSLZeroReturnError, SSLWantReadError, SSLWantWriteError,
-    SSLSyscallError, SSLEOFError, SSLCertVerificationError
+    SSLSyscallError, SSLEOFError, SSLCertVerificationError,
+    SSLECHRejectedError
     )
 from _ssl import txt2obj as _txt2obj, nid2obj as _nid2obj
 from _ssl import RAND_status, RAND_add, RAND_bytes
@@ -381,7 +382,8 @@ def _ipaddress_match(cert_ipaddress, host_ip):
     return ip == host_ip
 
 
-def _check_sslobject_params(server_side, context=None, server_hostname=None, session=None):
+def _check_sslobject_params(server_side, context=None, server_hostname=None,
+                            session=None, ech_config=None):
     """Raises a ValueError if SSLObject._create() parameters aren't valid.
     """
     if server_side:
@@ -391,6 +393,11 @@ def _check_sslobject_params(server_side, context=None, server_hostname=None, ses
         if session is not None:
             raise ValueError("session can only be specified in "
                              "client mode")
+        if ech_config is not None:
+            raise ValueError("ech_config can only be specified in "
+                             "client mode")
+    if ech_config is not None and not HAS_ECH:
+        raise NotImplementedError("ECH is not supported by the OpenSSL library")
     if context.check_hostname and not server_hostname:
         raise ValueError("check_hostname requires server_hostname")
 
@@ -471,7 +478,7 @@ def _encode_hostname(self, hostname):
     def wrap_socket(self, sock, server_side=False,
                     do_handshake_on_connect=True,
                     suppress_ragged_eofs=True,
-                    server_hostname=None, session=None):
+                    server_hostname=None, session=None, ech_config=None):
         # SSLSocket class handles server_hostname encoding before it calls
         # ctx._wrap_socket()
         return self.sslsocket_class._create(
@@ -481,17 +488,18 @@ def wrap_socket(self, sock, server_side=False,
             suppress_ragged_eofs=suppress_ragged_eofs,
             server_hostname=server_hostname,
             context=self,
-            session=session
+            session=session,
+            ech_config=ech_config,
         )
 
     def wrap_bio(self, incoming, outgoing, server_side=False,
-                 server_hostname=None, session=None):
+                 server_hostname=None, session=None, ech_config=None):
         # Need to encode server_hostname here because _wrap_bio() can only
         # handle ASCII str.
         return self.sslobject_class._create(
             incoming, outgoing, server_side=server_side,
             server_hostname=self._encode_hostname(server_hostname),
-            session=session, context=self,
+            session=session, context=self, ech_config=ech_config,
         )
 
     def set_npn_protocols(self, npn_protocols):
@@ -830,15 +838,19 @@ def __init__(self, *args, **kwargs):
 
     @classmethod
     def _create(cls, incoming, outgoing, server_side=False,
-                 server_hostname=None, session=None, context=None):
+                 server_hostname=None, session=None, context=None,
+                 ech_config=None):
         _check_sslobject_params(server_side=server_side, context=context,
-                                server_hostname=server_hostname, session=session)
+                                server_hostname=server_hostname,
+                                session=session, ech_config=ech_config)
         self = cls.__new__(cls)
         sslobj = context._wrap_bio(
             incoming, outgoing, server_side=server_side,
             server_hostname=server_hostname,
             owner=self, session=session
         )
+        if ech_config is not None:
+            sslobj.set_ech_config(ech_config)
         self._sslobj = sslobj
         return self
 
@@ -1007,6 +1019,14 @@ def verify_client_post_handshake(self):
         return self._sslobj.verify_client_post_handshake()
 
     if HAS_ECH:
+        def set_ech_config(self, ech_config):
+            """Set the ECH configuration for this connection.
+
+            This replaces any configuration inherited from the context
+            and must be called before the handshake starts.
+            """
+            self._sslobj.set_ech_config(ech_config)
+
         def get_ech_status(self):
             """Return the status of Encrypted Client Hello processing."""
             return ECHStatus(self._sslobj.get_ech_status()[0])
@@ -1041,11 +1061,12 @@ 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):
+                context=None, session=None, ech_config=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)
+                                server_hostname=server_hostname,
+                                session=session, ech_config=ech_config)
 
         sock_timeout = sock.gettimeout()
         kwargs = dict(
@@ -1059,6 +1080,7 @@ def _create(cls, sock, server_side=False, do_handshake_on_connect=True,
         try:
             self._context = context
             self._session = session
+            self._ech_config = ech_config
             self._closed = False
             self._sslobj = None
             self.server_side = server_side
@@ -1117,6 +1139,8 @@ def _create(cls, sock, server_side=False, do_handshake_on_connect=True,
                     self, server_side, self.server_hostname,
                     owner=self, session=self._session,
                 )
+                if self._ech_config is not None:
+                    self._sslobj.set_ech_config(self._ech_config)
                 if do_handshake_on_connect:
                     timeout = self.gettimeout()
                     if timeout == 0.0:
@@ -1450,6 +1474,12 @@ def verify_client_post_handshake(self):
             raise ValueError("No SSL wrapper around " + str(self))
 
     if HAS_ECH:
+        @_sslcopydoc
+        def set_ech_config(self, ech_config):
+            self._ech_config = ech_config
+            if self._sslobj is not None:
+                self._sslobj.set_ech_config(ech_config)
+
         @_sslcopydoc
         def get_ech_status(self):
             if self._sslobj is not None:
@@ -1487,6 +1517,8 @@ def _real_connect(self, addr, connect_ex):
             owner=self, session=self._session
         )
         try:
+            if self._ech_config is not None:
+                self._sslobj.set_ech_config(self._ech_config)
             if connect_ex:
                 rc = super().connect_ex(addr)
             else: