| 1 |
# TLS: ESNI support in curl and libcurl |
| 2 |
|
| 3 |
## Summary |
| 4 |
|
| 5 |
**ESNI** means **Encrypted Server Name Indication**, a TLS 1.3 |
| 6 |
extension which is currently the subject of an |
| 7 |
[IETF Draft][tlsesni]. |
| 8 |
|
| 9 |
This file is intended to show the latest current state of ESNI support |
| 10 |
in **curl** and **libcurl**. |
| 11 |
|
| 12 |
At end of August 2019, an [experimental fork of curl][niallorcurl], |
| 13 |
built using an [experimental fork of OpenSSL][sftcdopenssl], which in |
| 14 |
turn provided an implementation of ESNI, was demonstrated |
| 15 |
interoperating with a server belonging to the [DEfO |
| 16 |
Project][defoproj]. |
| 17 |
|
| 18 |
Further 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 |
|
| 31 |
To build and demonstrate ESNI support in **curl** and/or **libcurl**, |
| 32 |
you 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 |
|
| 47 |
The 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 |
|
| 97 |
The proposed change provides a framework to facilitate work to |
| 98 |
implement ESNI support in curl and libcurl. It is not intended |
| 99 |
either to provide ESNI functionality or to favour any particular |
| 100 |
TLS-providing backend. Specifically, the change reserves a |
| 101 |
feature bit for ESNI support (symbol `CURL_VERSION_ESNI`), |
| 102 |
implements setting and reporting of this bit, includes dummy |
| 103 |
book-keeping for the symbol, adds a build-time configuration |
| 104 |
option (`--enable-esni`), provides an extensible check for |
| 105 |
resources available to provide ESNI support, and defines a |
| 106 |
compiler pre-processor symbol (`USE_ESNI`) accordingly. |
| 107 |
|
| 108 |
Proposed-by: @niallor (Niall O'Reilly)\ |
| 109 |
Encouraged-by: @sftcd (Stephen Farrell)\ |
| 110 |
See-also: [this message](https://curl.haxx.se/mail/lib-2019-05/0108.html) |
| 111 |
|
| 112 |
Limitations: |
| 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 |
|
| 125 |
Cloudflare blog: [Encrypting SNI: Fixing One of the Core Internet Bugs][corebug] |
| 126 |
|
| 127 |
Cloudflare blog: [Encrypt it or lose it: how encrypted SNI works][esniworks] |
| 128 |
|
| 129 |
IETF 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 |