PlaceholderEncrypted Client Hello (ECH) is a TLS Extension which enhances the privacy of website connections by encrypting the TLS Client Hello with a public key fetched over DNS. ECH is undergoing standardization at the IETF, available as a[https://datatracker.ietf.org/doc/draft-ietf-tls-esni/ working group draft]. ECH. Firefox has implemented support for Encrypted Client Hello since Firefox 98 ([https://bugzilla.mozilla.org/show_bug.cgi?id=1725938 bug]). ==== What is ECH? ==== Encrypted Client Hello is an extension for TLS1.3. Clients that implement support add a new TLS extension to their Client Hello. Servers that do not implement support are required by the TLS1.3 specification to ignore the unrecognized extension. Servers that do implement support will try to process the extension and establish a connection using ECH. As well as implementing support, servers must also advertise a public key and other configuration values for use with ECH in their DNS records, using the new HTTPS resource record type. If the client has discovered an ECH configuration for use with the server in question, the ECH extension will contain encrypted data for the initial client hello, including the SNI (Server Name Indication) value. If not, the client will randomly generate an ECH extension which the server will necessarily ignore. This latter scenario is known as ECH GREASE (Generate Random Extensions And Sustain Extensibility) and used to ensure networks and servers correctly tolerate new ECH extensions. ECH has been carefully designed to interoperate with existing network practices. For example, if a browser has been configured by the user or administrator to trust an enterprise certificate authority (CA) which is then used to proxy TLS traffic, ECH will be securely downgraded by the proxy. This ensures that network administrators don’t need to worry about interference from ECH. Some enterprises do not use a transparent proxy and instead rely on passive SNI sniffing which is no longer possible with ECH. However, this technique has never been effective against malware or other security risks as malware is already able to spoof the SNI field. Further Reading: * Cloudflare’s [https://blog.cloudflare.com/handshake-encryption-endgame-an-ech-update/ explainer] on ECH’s design.* The IETF [https://www.ietf.org/archive/id/draft-ietf-tls-esni-16.html draft specification] for ECH. ==== ECH in Firefox ==== We implement support for the latest draft of Encrypted Client Hello. As is the norm, Firefox’s ECH behavior can be configured by a range of preferences which are detailed in their own section below. Enabling ECH results in Firefox sending a GREASE ECH extension for every connection (whether QUIC or TLS) and actively using ECH whenever Firefox discovers an ECH configuration for the site in question. Currently, Firefox can only fetch these ECH configurations over DoH (DNS over HTTPS), the benefits and drawbacks of which are discussed in the section below. ===== Dependency on DoH ===== ECH relies on a new type of DNS record which Firefox can currently only fetch via its DoH DNS stack. Support for fetching these records with the OS native resolver is tracked in bug[https://bugzilla.mozilla.org/show_bug.cgi?id=1500289 1500289]. Support via DoH has been prioritized because using unencrypted DNS with ECH delivers little overall benefit to user privacy. For the vast majority of users, their native OS resolver will use unencrypted DNS to contact their local router which in turn passes their queries unencrypted on to their network provider. Fetching ECHConfigs via unencrypted DNS means that the sites the user visits are still leaked in plaintext to the network and so ECH delivers little value in this scenario. For expert users, they may well use unencrypted local DNS but have configured their local DNS resolver to use a secure transport for reaching out across the network (e.g. with PiHole or similar). For such users, the easiest way to benefit from ECH and continue to use their local DNS resolver is to set up DNS-over-HTTPS locally. There are guides available for doing this, e.g. the instructions[https://github.com/DNSCrypt/dnscrypt-proxy/wiki/Local-DoH#built-in-doh-server--firefox-ech-encrypted-clienthello here] for DNSCrypt. In the long term, we will look at adding support for fetching ECHConfigs via the system resolver, but this requires work on each OS we support and so requires sustained investment in return for limited benefit. We may also start to see wider support for DoH by default in popular self-hosted DNS packages. ===== UX ===== We don’t currently expose ECH status in the browser. See the section below on how to test ECH. However: * Bug [https://bugzilla.mozilla.org/show_bug.cgi?id=1804460 1804460] tracks the work to expose ECH (and similar privacy features) in DevTools * ECH status can be accessed via the Extension API GetSecurityInfo, see the [https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/webRequest/SecurityInfo MDN documentation]. ====== Preferences ====== {| class="wikitable"|-! Pref Name! Description! Value Range! Enabled Value! Disabled Value|-| <code>network.dns.echconfig.enabled</code>| Whether to use ECH for TLS Connections| Boolean| True| False|-| <code>network.dns.http3_echconfig.enabled</code>| Whether to use ECH for QUIC connections| Boolean| True| False|-| <code>network.dns.echconfig.fallback_to_origin_when_all_failed</code>| Whether to fallback to non-ECH without an authenticated downgrade signal| Boolean| False| False|-| <code>security.tls.ech.grease_probability</code>| How often to GREASE connections with an inert ECH extension (only if an ECHConfig has not been discovered)| 0-100| 100| 0|-| <code>security.tls.ech.grease_size</code>| How much padding t add to ECH GREASE extensions| 0-255| 100| 100|-| <code>security.tls.ech.grease_http3</code>| Whether to GREASE QUIC connections| Boolean| True| False|-| <code>security.tls.ech.disable_grease_on_fallback</code>| Whether to disable ECH GREASE when retrying a connection| Boolean| False| False|-| <code>network.dns.force_waiting_https_rr</code>| Whether to wait for the HTTPS RR lookup to complete before starting a connection.| Boolean| True| True|} Note that DoH must also be enabled for ECH to be actively used. This is exposed as a user visible setting in <code>about:preferences</code>. See also the [https://wiki.mozilla.org/Trusted_Recursive_Resolver TRR Prefs] and the [https://wiki.mozilla.org/Security/DNS_Over_HTTPS DoH Prefs]. ==== Testing ECH and Reporting Bugs ==== ===== Possible Breakage ===== ECH GREASE adds an extension to ClientHellos which contains random data. The TLS1.3 and TLS1.2 specifications REQUIRE servers to ignore extensions they do not understand and so GREASE is unlikely to cause any issues. When a site opts in to ECH support by serving an ECHConfig in its DNS record, it is possible for an incorrect ECHConfig to break access to the site. For example, if the ECHConfig specifies a cover name which the responding server does not have a valid TLS certificate for and ECH negotiation fails, then the connection will result in a security error. ===== Testing whether ECH is responsible for breakage ===== ECH doesn’t introduce any new error pages which are user visible. However, as with any networking change, its possible for incompatibilities to arise. When evaluating whether an issue is due to ECH, the following steps are recommended: # Isolate whether the issue is due to ECH, ECH GREASE or neither. ## Disable ECH GREASE by setting <code>security.tls.ech.grease_probability</code> to <code>0</code> and <code>security.tls.ech.grease_http3</code> to <code>false</code>. Test if the issue still occurs. ## Disable ECH by setting <code>network.dns.echconfig.enabled</code> and <code>network.dns.http3_echconfig.enabled</code> to <code>false</code>. Test if the issue still occurs. ## If Step 1 fixed the issued, the problem is ECH GREASE. If Step 2 fixed the issue, the problem is with ECH itself. If neither fixed the issue, then the problem is very unlikely to be related to ECH. # If the issue is due to ECH or ECH GREASE, its then worth isolating whether the issue is specific to an implementation or common. You can do this by testing with Chrome Canary with the flag “EncryptedClientHello” set to true. If the issue also occurs with ECH enabled in Chrome and is fixed by disabling it, its likely an issue with the site or its configuration. # Please file a bug on Bugzilla blocking bug [https://bugzilla.mozilla.org/show_bug.cgi?id=1725938 1725938] with the answers to the above steps so that we can take a look. We are already aware of a limited number of sites with broken TLS servers which do not follow the specification (see below). ===== Testing whether ECH is working ===== There are various sites which can be used to test whether ECH was used in the connection: * https://www.cloudflare.com/ssl/encrypted-sni/* https://tls-ech.dev/* https://defo.ie/ech-check.php Tools like Wireshark can also be used to inspect TLS connection flows. ===== Known Incompatible Sites ===== We are aware of a very limited number of sites which do not correctly implement TLS. These sites are unable to handle TLS Client Hello messages with any unrecognised extension, despite the clear requirements in the specifications: <blockquote><pre class="">Servers MUST ignore unrecognized extensions.[...]A server receiving a ClientHello MUST correctly ignore all unrecognized cipher suites, extensions, and other parameters.</pre></blockquote>These sites do not have an ECH-specific incompatibility, they break for all new extensions they do not recognise. We’ve reached out to the site operators to inform them of the problem. ==== ECH around the Web ==== The [https://defo.ie/ DEfO project] and the [https://guardianproject.info/2021/11/30/implementing-tls-encrypted-client-hello/ Guardian Project] have implemented ECH support in a number of applications: * [https://github.com/sftcd/openssl/tree/ECH-draft-13c OpenSSL] * [https://github.com/sftcd/curl/blob/ECH-experimental/docs/ECH.md curl]* [https://github.com/sftcd/nginx nginx]* [https://github.com/sftcd/httpd apache]* [https://github.com/sftcd/lighttpd1.4 lighttpd]* [https://github.com/sftcd/haproxy/commits/ECH-experimental HAProxy]* [https://github.com/guardianproject/conscrypt/tree/2.6.alpha1638179154.job1828169525 Conscrypt] Support is also available in Firefox and Chromium. Webkit / Safari have [https://github.com/WebKit/standards-positions/issues/46 indicated] support for ECH, but have not implemented it. Caddy has yet to make a [https://github.com/caddyserver/caddy/issues/4221 decision].
