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     ! 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