Return to ESNI.md CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / curl / docs

curl

    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