From cbe7fad20d969626a5c4eb0501a273dfe812bcd3 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 29 Sep 2020 10:13:18 +0200 Subject: [PATCH] ECH: renamed from ESNI in docs and configure Encrypted Client Hello (ECH) is the current name. Closes #6022 --- configure.ac | 36 +++++++++---------- docs/{ESNI.md => ECH.md} | 74 +++++++++++++++++++--------------------- docs/Makefile.am | 2 +- m4/curl-confopts.m4 | 40 +++++++++++----------- 4 files changed, 74 insertions(+), 78 deletions(-) rename docs/{ESNI.md => ECH.md} (57%) diff --git a/configure.ac b/configure.ac index db0621c18..504b902cc 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/ESNI.md b/docs/ECH.md similarity index 57% rename from docs/ESNI.md rename to 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 \ 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. +dnl --enable-ech or --disable-ech, and set +dnl shell variable want_ech 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 +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