Debian Codegraph @

deps/curl/docs/ESNI.md

raw
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