Developing ECH for OpenSSL (DEfO)

The encrypted ClientHello (ECH) mechanism (draft-spec) is a way to plug a few privacy-holes that remain in the Transport Layer Security (TLS) protocol that's used as the security layer for the web. OpenSSL is a widely used library that provides an implementation of the TLS protocol. The DEfO project is developing an implementation of ECH for OpenSSL, and various clients and servers that use OpenSSL as a demonstration and for interoperability testing. DEfO was initially funded by the Open Technology Fund, and subsequently by the National Democratic Initiative. Tolerant Networks Ltd. and people from the Guardian Project are doing the work in DEfO.

This site is for ECH interoperability testing. The table below indicates the various combinations of server technology supported here.

This is not a highly-scalable hugely-tested thing - let us know if you find any issues, but do expect to find issues - that's what this site is for after all!

As of 20220824 we've done some good interop testing with our draft-13 code. That's the latest interop target. We seem to work fine with the boringssl, and NSS libraries, with the Cloudflare server, and with the Firefox, Chromium and Brave browsers.

Servers

So what's deployed here is:

Server Technology	URL/host:port details
nginx	https://defo.ie/ech-check.php a web page that tells you if ECH was used
OpenSSL s_server	https://draft-13.esni.defo.ie:8413/stats for "normal ECH" or https://draft-13.esni.defo.ie:8414/stats for one that forces HRR to P-384
lighttpd 1.4	https://draft-13.esni.defo.ie:9413/
nginx	https://draft-13.esni.defo.ie:10413/
apache2	https://draft-13.esni.defo.ie:11413/
haproxy	https://draft-13.esni.defo.ie:12413/ - haproxy shared mode (haproxy terminates TLS) https://draft-13.esni.defo.ie:12414/ - haproxy split mode (haproxy only decrypts ECH)

ECH public keys for those servers are published in the DNS. For ports 443, 12413 and 12414 (the latter two being haproxy services) we don't rotate those keys. For ports 8413, 8414, 9414, 10413 and 11413 we are currently publishing one HTTPS RR containing 3 public keys: the first is a long term ECH public key, the other two are short-term keys. Short term keys are usable for three hours, but only published for two hours, after which they are no longer published but are still usable for the third hour. A new short term key is generated hourly, so we publish 2 short term keys at any given moment. All 3 ECHConfig values are inside one ECHConfigList.

In addition, to help with testing, we are publishing some "broken" or "odd" HTTPS RRs for port 13413. Those will also change hourly, and you can find details here.

As of 2021-12-01, we've turned off the servers we used operate for draft-10 and draft-02. Happy to turn those back on if needed, just send us mail. (Hasn't happened yet, and I bet it won't:-)

Clients

Firefox (perhaps only nightly?) supports ECH draft-13. To enable ECH for Firefox, you first need to turn on DNS-over-HTTPS (DoH, set TRR mode=2) and then also manually enable the "network.dns.echconfig.enabled" setting via "about:config".

Chromium (version 105+) now also supports ECH, but again behind a flag and you also need DoH turned on. To turn on DoH, you need to go to "chrome://settings/security" scroll down some and then enable "Use Secure DNS." To then enable ECH, goto "chrome://flags/", search for "encrypted clienthello" and enable that.

Brave (nightly) from version 105 on also supports ECH. Follow the installation instructions, then run brave-browser-nightly, turn on DoH via brave://settings/security then scroll down to the "Use secure DNS" place and enable some server, next go to brave://flags, search for "Encrypted ClientHello" and choose enable, then do the same for "Support for HTTPS records in DNS." After a browser re-start, you should be flying with ECH.

To do other tests you need to build from source for either our openssl s_client or curl, or use one of the Java clients we've developed that run on top of Conscrypt/boringssl..

With "s_client" for each of the servers running on draft-13.esni.defo.ie you can test using e.g: "$HOME/code/openssl/esnistuff/echcli.sh -p 8413 -H draft-13.esni.defo.ie" - that will also work against Cloudflare.
For curl, you can follow our build and test instructions.
We have demo fork of F-Droid to serve as an example app built on the development fork of Conscrypt. We hope to make that really usable as the server side of F-droid runs on Cloudflare.
ECHInteropTest is a simple example app built on our Conscrypt fork to test TLS Encrypted ClientHello (ECH) interoperability between various implementations, platforms, and networks. This runs as standard Android unit tests on the emulator.
We also have test scripts allowing tests with NSS' tstclnt and boringssl's s_client. Apoloigies that those aren't documented, if you need to use them, just send us email.

More implementations

The TLS WG maintain a page with information about our and other implementations.

This fine domain brought to you by Tolerant Networks Limited.
Last modified: 2022-08-24, but who cares?

This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.