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