diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/ECH.md (renamed from docs/ESNI.md) | 74 | ||||
| -rw-r--r-- | docs/Makefile.am | 2 |
2 files changed, 36 insertions, 40 deletions
diff --git a/docs/ESNI.md b/docs/ECH.md index 7feaa75ad..ea1efaa67 100644 --- a/docs/ESNI.md +++ b/docs/ECH.md @@ -1,24 +1,23 @@ -# TLS: ESNI support in curl and libcurl +# TLS: ECH 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]. +**ECH** means **Encrypted Client Hello**, a TLS 1.3 extension which is +currently the subject of an [IETF Draft][tlsesni]. (ECH was formerly known as +ESNI). -This file is intended to show the latest current state of ESNI support +This file is intended to show the latest current state of ECH 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]. +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 ECH, 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, + for ECH, - progress to date, @@ -28,18 +27,18 @@ Further sections here describe ## Resources needed -To build and demonstrate ESNI support in **curl** and/or **libcurl**, +To build and demonstrate ECH support in **curl** and/or **libcurl**, you will need -- a TLS library, supported by **libcurl**, which implements ESNI; +- a TLS library, supported by **libcurl**, which implements ECH; -- an edition of **curl** and/or **libcurl** which supports the ESNI +- an edition of **curl** and/or **libcurl** which supports the ECH 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 +- a server, supporting ECH, against which to run a demonstration and perhaps a specific target URL; - some instructions. @@ -58,52 +57,49 @@ The following set of resources is currently known to be available. - Details [below](#pr4011); -- New **curl** feature: `CURL_VERSION_ESNI`; +- New configuration option: `--enable-ech`; -- New configuration option: `--enable-esni`; - -- Build-time check for availability of resources needed for ESNI +- Build-time check for availability of resources needed for ECH support; -- Pre-processor symbol `USE_ESNI` for conditional compilation of - ESNI support code, subject to configuration option and +- Pre-processor symbol `USE_ECH` for conditional compilation of + ECH support code, subject to configuration option and availability of needed resources. ## TODO -- (next PR) Add libcurl options to set ESNI parameters. +- (next PR) Add libcurl options to set ECH parameters. -- (next PR) Add curl tool command line options to set ESNI parameters. +- (next PR) Add curl tool command line options to set ECH parameters. -- (WIP) Extend DoH functions so that published ESNI parameters can be +- (WIP) Extend DoH functions so that published ECH parameters can be retrieved from DNS instead of being required as options. -- (WIP) Work with OpenSSL community to finalize ESNI API. +- (WIP) Work with OpenSSL community to finalize ECH API. -- Track OpenSSL ESNI API in libcurl +- Track OpenSSL ECH 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. +- Encourage ECH support work on other TLS/SSL backends. ## Additional detail ### PR 4011 -**TLS: Provide ESNI support framework for curl and libcurl** +**TLS: Provide ECH 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. +The proposed change provides a framework to facilitate work to implement ECH +support in curl and libcurl. It is not intended either to provide ECH +functionality or to favour any particular TLS-providing backend. Specifically, +the change reserves a feature bit for ECH support (symbol +`CURL_VERSION_ECH`), implements setting and reporting of this bit, includes +dummy book-keeping for the symbol, adds a build-time configuration option +(`--enable-ech`), provides an extensible check for resources available to +provide ECH support, and defines a compiler pre-processor symbol (`USE_ECH`) +accordingly. Proposed-by: @niallor (Niall O'Reilly)\ Encouraged-by: @sftcd (Stephen Farrell)\ @@ -117,7 +113,7 @@ Limitations: - 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 + implement ECH for OpenSSL, as this is the immediate motivation for the proposed change. ## References diff --git a/docs/Makefile.am b/docs/Makefile.am index 5e3cfdca0..b7d179228 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -56,7 +56,7 @@ EXTRA_DIST = \ CURL-DISABLE.md \ DEPRECATE.md \ DYNBUF.md \ - ESNI.md \ + ECH.md \ EXPERIMENTAL.md \ FAQ \ FEATURES \ |