Return to ESNI.md CVS log

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

Annotation of embedaddon/curl/docs/ESNI.md, revision 1.1.1.1

1.1       misho       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