From f230b1d1b2189aec383c47baad602d7a4b4dc550 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 29 Sep 2020 10:13:18 +0200 Subject: ECH: renamed from ESNI in docs and configure Encrypted Client Hello (ECH) is the curernt name. --- configure.ac | 36 +++++++------- docs/ECH.md | 135 ++++++++++++++++++++++++++++++++++++++++++++++++++ docs/ESNI.md | 139 ---------------------------------------------------- docs/Makefile.am | 2 +- m4/curl-confopts.m4 | 42 ++++++++-------- 5 files changed, 175 insertions(+), 179 deletions(-) create mode 100644 docs/ECH.md delete mode 100644 docs/ESNI.md diff --git a/configure.ac b/configure.ac index 433a5c22b..d27d9c873 100755 --- a/configure.ac +++ b/configure.ac @@ -49,7 +49,7 @@ CURL_CHECK_OPTION_CURLDEBUG CURL_CHECK_OPTION_SYMBOL_HIDING CURL_CHECK_OPTION_ARES CURL_CHECK_OPTION_RT -CURL_CHECK_OPTION_ESNI +CURL_CHECK_OPTION_ECH XC_CHECK_PATH_SEPARATOR @@ -4873,32 +4873,32 @@ if test "$enable_altsvc" = "yes"; then fi dnl ************************************************************* -dnl check whether ESNI support, if desired, is actually available +dnl check whether ECH support, if desired, is actually available dnl -if test "x$want_esni" != "xno"; then - AC_MSG_CHECKING([whether ESNI support is available]) +if test "x$want_ech" != "xno"; then + AC_MSG_CHECKING([whether ECH support is available]) dnl assume NOT and look for sufficient condition - ESNI_ENABLED=0 - ESNI_SUPPORT='' + ECH_ENABLED=0 + ECH_SUPPORT='' - dnl OpenSSL with a chosen ESNI function should be enough + dnl OpenSSL with a chosen ECH function should be enough dnl so more exhaustive checking seems unnecessary for now if test "x$OPENSSL_ENABLED" = "x1"; then - AC_CHECK_FUNCS(SSL_get_esni_status, - ESNI_SUPPORT="ESNI support available (OpenSSL with SSL_get_esni_status)" - ESNI_ENABLED=1) + AC_CHECK_FUNCS(SSL_get_ech_status, + ECH_SUPPORT="ECH support available (OpenSSL with SSL_get_ech_status)" + ECH_ENABLED=1) dnl add 'elif' chain here for additional implementations fi dnl now deal with whatever we found - if test "x$ESNI_ENABLED" = "x1"; then - AC_DEFINE(USE_ESNI, 1, [if ESNI support is available]) - AC_MSG_RESULT($ESNI_SUPPORT) - experimental="$experimental ESNI" + if test "x$ECH_ENABLED" = "x1"; then + AC_DEFINE(USE_ECH, 1, [if ECH support is available]) + AC_MSG_RESULT($ECH_SUPPORT) + experimental="$experimental ECH" else - AC_MSG_ERROR([--enable-esni ignored: No ESNI support found]) + AC_MSG_ERROR([--enable-ech ignored: No ECH support found]) fi fi @@ -5034,8 +5034,8 @@ if test "x$OPENSSL_ENABLED" = "x1" -o "x$GNUTLS_ENABLED" = "x1" \ SUPPORT_FEATURES="$SUPPORT_FEATURES HTTPS-proxy" fi -if test "x$ESNI_ENABLED" = "x1"; then - SUPPORT_FEATURES="$SUPPORT_FEATURES ESNI" +if test "x$ECH_ENABLED" = "x1"; then + SUPPORT_FEATURES="$SUPPORT_FEATURES ECH" fi dnl replace spaces with newlines @@ -5233,7 +5233,7 @@ AC_MSG_NOTICE([Configured to build curl/libcurl: Alt-svc: ${curl_altsvc_msg} HTTP2: ${curl_h2_msg} HTTP3: ${curl_h3_msg} - ESNI: ${curl_esni_msg} + ECH: ${curl_ech_msg} Protocols: ${SUPPORT_PROTOCOLS} Features: ${SUPPORT_FEATURES} ]) diff --git a/docs/ECH.md b/docs/ECH.md new file mode 100644 index 000000000..ea1efaa67 --- /dev/null +++ b/docs/ECH.md @@ -0,0 +1,135 @@ +# TLS: ECH support in curl and libcurl + +## Summary + +**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 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 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 ECH, + +- progress to date, + +- TODO items, and + +- additional details of specific stages of the progress. + +## Resources needed + +To build and demonstrate ECH support in **curl** and/or **libcurl**, +you will need + +- a TLS library, supported by **libcurl**, which implements ECH; + +- 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 ECH, 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 configuration option: `--enable-ech`; + +- Build-time check for availability of resources needed for ECH + support; + +- 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 ECH parameters. + +- (next PR) Add curl tool command line options to set ECH parameters. + +- (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 ECH API. + +- Track OpenSSL ECH API in libcurl + +- Identify and implement any changes needed for CMake. + +- Optimize build-time checking of available resources. + +- Encourage ECH support work on other TLS/SSL backends. + +## Additional detail + +### PR 4011 + +**TLS: Provide ECH support framework for curl and libcurl** + +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)\ +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 ECH 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 diff --git a/docs/ESNI.md b/docs/ESNI.md deleted file mode 100644 index 7feaa75ad..000000000 --- a/docs/ESNI.md +++ /dev/null @@ -1,139 +0,0 @@ -# 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 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 \ diff --git a/m4/curl-confopts.m4 b/m4/curl-confopts.m4 index eaae5b9c6..5f877133a 100644 --- a/m4/curl-confopts.m4 +++ b/m4/curl-confopts.m4 @@ -649,37 +649,37 @@ AC_DEFUN([CURL_CHECK_NTLM_WB], [ fi ]) -dnl CURL_CHECK_OPTION_ESNI +dnl CURL_CHECK_OPTION_ECH dnl ----------------------------------------------------- dnl Verify whether configure has been invoked with option -dnl --enable-esni or --disable-esni, and set -dnl shell variable want_esni as appropriate. - -AC_DEFUN([CURL_CHECK_OPTION_ESNI], [ - AC_MSG_CHECKING([whether to enable ESNI support]) - OPT_ESNI="default" - AC_ARG_ENABLE(esni, -AC_HELP_STRING([--enable-esni],[Enable ESNI support]) -AC_HELP_STRING([--disable-esni],[Disable ESNI support]), - OPT_ESNI=$enableval) - case "$OPT_ESNI" in +dnl --enable-ech or --disable-ech, and set +dnl shell variable want_ech as appropriate. + +AC_DEFUN([CURL_CHECK_OPTION_ECH], [ + AC_MSG_CHECKING([whether to enable ECH support]) + OPT_ECH="default" + AC_ARG_ENABLE(ech, +AC_HELP_STRING([--enable-ech],[Enable ECH support]) +AC_HELP_STRING([--disable-ech],[Disable ECH support]), + OPT_ECH=$enableval) + case "$OPT_ECH" in no) - dnl --disable-esni option used - want_esni="no" - curl_esni_msg="no (--enable-esni)" + dnl --disable-ech option used + want_ech="no" + curl_ech_msg="no (--enable-ech)" AC_MSG_RESULT([no]) ;; default) dnl configure option not specified - want_esni="no" - curl_esni_msg="no (--enable-esni)" + want_ech="no" + curl_ech_msg="no (--enable-ech)" AC_MSG_RESULT([no]) ;; *) - dnl --enable-esni option used - want_esni="yes" - curl_esni_msg="enabled (--disable-esni)" - experimental="esni" + dnl --enable-ech option used + want_ech="yes" + curl_ech_msg="enabled (--disable-ech)" + experimental="ech" AC_MSG_RESULT([yes]) ;; esac -- cgit v1.2.1