1# TLS: ECH support in curl and libcurl 2 3## Summary 4 5**ECH** means **Encrypted Client Hello**, a TLS 1.3 extension which is 6currently the subject of an [IETF Draft][tlsesni]. (ECH was formerly known as 7ESNI). 8 9This file is intended to show the latest current state of ECH support 10in **curl** and **libcurl**. 11 12At end of August 2019, an [experimental fork of curl][niallorcurl], built 13using an [experimental fork of OpenSSL][sftcdopenssl], which in turn provided 14an implementation of ECH, was demonstrated interoperating with a server 15belonging to the [DEfO Project][defoproj]. 16 17Further sections here describe 18 19- resources needed for building and demonstrating **curl** support 20 for ECH, 21 22- progress to date, 23 24- TODO items, and 25 26- additional details of specific stages of the progress. 27 28## Resources needed 29 30To build and demonstrate ECH support in **curl** and/or **libcurl**, 31you will need 32 33- a TLS library, supported by **libcurl**, which implements ECH; 34 35- an edition of **curl** and/or **libcurl** which supports the ECH 36 implementation of the chosen TLS library; 37 38- an environment for building and running **curl**, and at least 39 building **OpenSSL**; 40 41- a server, supporting ECH, against which to run a demonstration 42 and perhaps a specific target URL; 43 44- some instructions. 45 46The following set of resources is currently known to be available. 47 48| Set | Component | Location | Remarks | 49|:-----|:-------------|:------------------------------|:-------------------------------------------| 50| DEfO | TLS library | [sftcd/openssl][sftcdopenssl] | Tag *esni-2019-08-30* avoids bleeding edge | 51| | curl fork | [niallor/curl][niallorcurl] | Tag *esni-2019-08-30* likewise | 52| | instructions | [ESNI-README][niallorreadme] | | 53 54## Progress 55 56### PR 4011 (Jun 2019) expected in curl release 7.67.0 (Oct 2019) 57 58- Details [below](#pr4011); 59 60- New configuration option: `--enable-ech`; 61 62- Build-time check for availability of resources needed for ECH 63 support; 64 65- Pre-processor symbol `USE_ECH` for conditional compilation of 66 ECH support code, subject to configuration option and 67 availability of needed resources. 68 69## TODO 70 71- (next PR) Add libcurl options to set ECH parameters. 72 73- (next PR) Add curl tool command line options to set ECH parameters. 74 75- (WIP) Extend DoH functions so that published ECH parameters can be 76 retrieved from DNS instead of being required as options. 77 78- (WIP) Work with OpenSSL community to finalize ECH API. 79 80- Track OpenSSL ECH API in libcurl 81 82- Identify and implement any changes needed for CMake. 83 84- Optimize build-time checking of available resources. 85 86- Encourage ECH support work on other TLS/SSL backends. 87 88## Additional detail 89 90### PR 4011 91 92**TLS: Provide ECH support framework for curl and libcurl** 93 94The proposed change provides a framework to facilitate work to implement ECH 95support in curl and libcurl. It is not intended either to provide ECH 96functionality or to favour any particular TLS-providing backend. Specifically, 97the change reserves a feature bit for ECH support (symbol 98`CURL_VERSION_ECH`), implements setting and reporting of this bit, includes 99dummy book-keeping for the symbol, adds a build-time configuration option 100(`--enable-ech`), provides an extensible check for resources available to 101provide ECH support, and defines a compiler pre-processor symbol (`USE_ECH`) 102accordingly. 103 104Proposed-by: @niallor (Niall O'Reilly)\ 105Encouraged-by: @sftcd (Stephen Farrell)\ 106See-also: [this message](https://curl.haxx.se/mail/lib-2019-05/0108.html) 107 108Limitations: 109- Book-keeping (symbols-in-versions) needs real release number, not 'DUMMY'. 110 111- Framework is incomplete, as it covers autoconf, but not CMake. 112 113- Check for available resources, although extensible, refers only to 114 specific work in progress ([described 115 here](https://github.com/sftcd/openssl/tree/master/esnistuff)) to 116 implement ECH for OpenSSL, as this is the immediate motivation 117 for the proposed change. 118 119## References 120 121Cloudflare blog: [Encrypting SNI: Fixing One of the Core Internet Bugs][corebug] 122 123Cloudflare blog: [Encrypt it or lose it: how encrypted SNI works][esniworks] 124 125IETF Draft: [Encrypted Server Name Indication for TLS 1.3][tlsesni] 126 127--- 128 129[tlsesni]: https://datatracker.ietf.org/doc/draft-ietf-tls-esni/ 130[esniworks]: https://blog.cloudflare.com/encrypted-sni/ 131[corebug]: https://blog.cloudflare.com/esni/ 132[defoproj]: https://defo.ie/ 133[sftcdopenssl]: https://github.com/sftcd/openssl/ 134[niallorcurl]: https://github.com/niallor/curl/ 135[niallorreadme]: https://github.com/niallor/curl/blob/master/ESNI-README.md 136