diff options
Diffstat (limited to 'docs/ESNI.md')
| -rw-r--r-- | docs/ESNI.md | 139 |
1 files changed, 139 insertions, 0 deletions
diff --git a/docs/ESNI.md b/docs/ESNI.md new file mode 100644 index 000000000..eefb6662b --- /dev/null +++ b/docs/ESNI.md @@ -0,0 +1,139 @@ +# TLS: ESNI support in curl and libcurl + +## Summary + +**ESNI** means **Encrypted Server Name Indication**, a TLS 1.3 +extension which is currently the subject of an +[IETF Draft][tlsesni]. + +This file is intended to show the latest current state of ESNI support +in **curl** and **libcurl**. + +At end of August 2019, an [experimental fork of curl][niallorcurl], +built using an [experimental fork of OpenSSL][sftcdopenssl], which in +turn provided an implementation of ESNI, was demonstrated +interoperating with a server belonging to the [DEfO +Project][defoproj]. + +Further sections here describe + +- resources needed for building and demonstrating **curl** support + for ESNI, + +- progress to date, + +- TODO items, and + +- additional details of specific stages of the progress. + +## Resources needed + +To build and demonstrate ESNI support in **curl** and/or **libcurl**, +you will need + +- a TLS library, supported by **libcurl**, which implements ESNI; + +- an edition of **curl** and/or **libcurl** which supports the ESNI + implementation of the chosen TLS library; + +- an environment for building and running **curl**, and at least + building **OpenSSL**; + +- a server, supporting ESNI, against which to run a demonstration + and perhaps a specific target URL; + +- some instructions. + +The following set of resources is currently known to be available. + +| Set | Component | Location | Remarks | +|:-----|:-------------|:------------------------------|:-------------------------------------------| +| DEfO | TLS library | [sftcd/openssl][sftcdopenssl] | Tag *esni-2019-08-30* avoids bleeding edge | +| | curl fork | [niallor/curl][niallorcurl] | Tag *esni-2019-08-30* likewise | +| | instructions | [ESNI-README][niallorreadme] | | + +## Progress + +### PR 4011 (Jun 2019) expected in curl release 7.67.0 (Oct 2019) + +- Details [below](#pr4011); + +- New **curl** feature: `CURL_VERSION_ESNI`; + +- New configuration option: `--enable-esni`; + +- Build-time check for availability of resources needed for ESNI + support; + +- Pre-processor symbol `USE_ESNI` for conditional compilation of + ESNI support code, subject to configuration option and + availability of needed resources. + +## TODO + +- (next PR) Add libcurl options to set ESNI parameters. + +- (next PR) Add curl tool command line options to set ESNI parameters. + +- (WIP) Extend DoH functions so that published ESNI parameters can be + retrieved from DNS instead of being required as options. + +- (WIP) Work with OpenSSL community to finalize ESNI API. + +- Track OpenSSL ESNI API in libcurl + +- Identify and implement any changes needed for CMake. + +- Optimize build-time checking of available resources. + +- Encourage ESNI support work on other TLS/SSL backends. + +## Additional detail + +### PR 4011 + +**TLS: Provide ESNI support framework for curl and libcurl** + +The proposed change provides a framework to facilitate work to +implement ESNI support in curl and libcurl. It is not intended +either to provide ESNI functionality or to favour any particular +TLS-providing backend. Specifically, the change reserves a +feature bit for ESNI support (symbol `CURL_VERSION_ESNI`), +implements setting and reporting of this bit, includes dummy +book-keeping for the symbol, adds a build-time configuration +option (`--enable-esni`), provides an extensible check for +resources available to provide ESNI support, and defines a +compiler pre-processor symbol (`USE_ESNI`) accordingly. + +Proposed-by: @niallor (Niall O'Reilly)\ +Encouraged-by: @sftcd (Stephen Farrell)\ +See-also: [this message](https://curl.haxx.se/mail/lib-2019-05/0108.html) + +Limitations: +- Book-keeping (symbols-in-versions) needs real release number, not 'DUMMY'. + +- Framework is incomplete, as it covers autoconf, but not CMake. + +- Check for available resources, although extensible, refers only to + specific work in progress ([described + here](https://github.com/sftcd/openssl/tree/master/esnistuff)) to + implement ESNI for OpenSSL, as this is the immediate motivation + for the proposed change. + +## References + +CloudFlare blog: [Encrypting SNI: Fixing One of the Core Internet Bugs][corebug] + +Cloudflare blog: [Encrypt it or lose it: how encrypted SNI works][esniworks] + +IETF Draft: [Encrypted Server Name Indication for TLS 1.3][tlsesni] + +--- + +[tlsesni]: https://datatracker.ietf.org/doc/draft-ietf-tls-esni/ +[esniworks]: https://blog.cloudflare.com/encrypted-sni/ +[corebug]: https://blog.cloudflare.com/esni/ +[defoproj]: https://defo.ie/ +[sftcdopenssl]: https://github.com/sftcd/openssl/ +[niallorcurl]: https://github.com/niallor/curl/ +[niallorreadme]: https://github.com/niallor/curl/blob/master/ESNI-README.md |