Lines Matching +full:- +full:- +full:with +full:- +full:wolfssl
1 <!--
4 SPDX-License-Identifier: curl
5 -->
7 # Building curl with HTTPS-RR and ECH support
11 ECHConfigList values from the command line. That works with OpenSSL,
12 WolfSSL or boringssl as the TLS provider, depending on how you build curl.
16 This should however provide enough of a proof-of-concept to prompt an informed
22 To build our ECH-enabled OpenSSL fork:
26 git clone https://github.com/defo-project/openssl
28 ./config --libdir=lib --prefix=$HOME/code/openssl-local-inst
30 make -j8
36 To build curl ECH-enabled, making use of the above:
42 autoreconf -fi
43 …LDFLAGS="-Wl,-rpath,$HOME/code/openssl-local-inst/lib/" ./configure --with-ssl=$HOME/code/openssl-…
51 is not enabled, so go back some steps and re-do whatever needs re-doing:-) If you
52 want to debug curl then you should add ``--enable-debug`` to the ``configure``
55 In a recent (2024-05-20) build on one machine, configure failed to find the
56 ECH-enabled SSL library, apparently due to the existence of
57 ``$HOME/code/openssl-local-inst/lib/pkgconfig`` as a directory containing
68 …ARY_PATH=$HOME/code/openssl ./src/curl --ech true --doh-url https://one.one.one.one/dns-query http…
70 SSL_ECH_STATUS: success <img src="greentick-small.png" alt="good" /> <br/>
79 https://defo.ie/ech-check.php
80 https://draft-13.esni.defo.ie:8413/stats
81 https://draft-13.esni.defo.ie:8414/stats
82 https://crypto.cloudflare.com/cdn-cgi/trace
83 https://tls-ech.dev
92 - ``--ech <config>`` - the ``config`` value can be one of:
93 - ``false`` says to not attempt ECH
94 - ``true`` says to attempt ECH, if possible
95 - ``grease`` if attempting ECH is not possible, then send a GREASE ECH extension
96 - ``hard`` hard-fail the connection if ECH cannot be attempted
97 - ``ecl:<b64value>`` a base64 encoded ECHConfigList, rather than one accessed from the DNS
98 - ``pn:<name>`` over-ride the ``public_name`` from an ECHConfigList
101 ClientHello with a "real" ECH extension, but that does not mean that the
108 cut-and-paste, e.g.:
118 …enssl ./src/curl --ech ecl:AED+DQA8PAAgACD8WhlS7VwEt5bf3lekhHvXrQBGDrZh03n/LsNtAodbUAAEAAEAAQANY29…
120 SSL_ECH_STATUS: success <img src="greentick-small.png" alt="good" /> <br/>
130 …sl ./src/curl -vvv --ech ecl:AED+DQA8yAAgACDRMQo+qYNsNRNj+vfuQfFIkrrUFmM4vogucxKj/4nzYgAEAAEAAQANY…
136 There is a reason to want this command line option - for use before publishing
137 an ECHConfigList in the DNS as per the Internet-draft [A well-known URI for
138 publishing ECHConfigList values](https://datatracker.ietf.org/doc/draft-ietf-tls-wkech/).
145 …sl ./src/curl -vvv --ech ecl:AED+DQA8yAAgACDRMQo+qYNsNRNj+vfuQfFIkrrUFmM4vogucxKj/4nzYgAEAAEAAQANY…
162 doh-url=https://one.one.one.one/dns-query
167 Note that when you use the system's curl command (rather than our ECH-enabled
169 issue (e.g. if some script re-directs stdout and stderr somewhere) then adding
171 course, yet another script could depend on non-silent behavior, so you may have
172 to figure out what you prefer yourself.) That seems to have changed with the
193 With all that setup as above the command line gets simpler:
196 ./src/curl https://defo.ie/ech-check.php
198 SSL_ECH_STATUS: success <img src="greentick-small.png" alt="good" /> <br/>
202 The ``--ech true`` option is opportunistic, so tries to do ECH but does not fail if
203 the client for example cannot find any ECHConfig values. The ``--ech hard``
204 option hard-fails if there is no ECHConfig found in DNS, so for now, that is not
212 - ``USE_HTTPSRR`` is used for HTTPS RR retrieval code that could be generically
213 used should non-ECH uses for HTTPS RRs be identified, e.g. use of ALPN values
216 - ``USE_ECH`` protects ECH specific code.
225 determined:-)
230 purpose. This code also implements the opportunistic (``--ech true``) or hard-fail
231 (``--ech hard``) logic.
234 where we re-use ``dohprobe()`` to retrieve an HTTPS RR value for the target
251 - We could easily add code to make use of an ``alpn=`` value found in an HTTPS
257 - Only the first HTTPS RR value retrieved is actually processed as described
259 could be non-trivial if multiple RRs are published - matching IP address hints
262 needs re-checking as it has been a while.
264 - It is unclear how one should handle any IP address hints found in an HTTPS RR.
265 It may be that a bit of consideration of how "multi-CDN" deployments might
269 - The SVCB/HTTPS RR specification supports a new "CNAME at apex" indirection
270 ("aliasMode") - the current code takes no account of that at all. One could
276 - We have not investigated what related changes or additions might be needed
280 - We have not yet implemented tests as part of the usual curl test harness as
281 doing so would seem to require re-implementing an ECH-enabled server as part
283 that attempts ECH with various test servers and with many combinations of the
290 ## Building with cmake
292 To build with cmake, assuming our ECH-enabled OpenSSL is as before:
300 cmake -DOPENSSL_ROOT_DIR=$HOME/code/openssl -DUSE_ECH=1 -DUSE_HTTPSRR=1 ..
307 The binary produced by the cmake build does not need any ECH-specific
313 with that, instead of our ECH-enabled OpenSSL:
319 cmake -DCMAKE_INSTALL_PREFIX:PATH=$HOME/code/boringssl/inst -DBUILD_SHARED_LIBS=1
331 autoreconf -fi
332 …LDFLAGS="-Wl,-rpath,$HOME/code/boringssl/inst/lib" ./configure --with-ssl=$HOME/code/boringssl/ins…
334 WARNING: ech ECH HTTPSRR enabled but marked EXPERIMENTAL. Use with caution!
338 The boringssl APIs are fairly similar to those in our ECH-enabled OpenSSL
342 The boringssl APIs however do not support the ``--ech pn:`` command line
345 ## WolfSSL build
347 WolfSSL also supports ECH and can be used by curl, so here's how:
351 git clone https://github.com/wolfSSL/wolfssl
352 cd wolfssl
354 ./configure --prefix=$HOME/code/wolfssl/inst --enable-ech --enable-debug --enable-opensslextra
359 The install prefix (``inst``) in the above causes WolfSSL to be installed there
361 ``--enable-opensslextra`` turns out (after much faffing about;-) to be
362 important or else we get build problems with curl below.
368 autoreconf -fi
369 ./configure --with-wolfssl=$HOME/code/wolfssl/inst --enable-ech --enable-httpsrr
373 There are some known issues with the ECH implementation in WolfSSL:
375 - The main issue is that the client currently handles HelloRetryRequest
376 incorrectly. [HRR issue](https://github.com/wolfSSL/wolfssl/issues/6802).)
378 [this ECH test web site](https://tls-ech.dev) and any other similarly configured
380 - There is also an issue related to so-called middlebox compatibility mode.
381 [middlebox compatibility issue](https://github.com/wolfSSL/wolfssl/issues/6774)
383 ### Code changes to support WolfSSL
387 - The DoH URL in``$HOME/.curlrc`` can use "1.1.1.1" for OpenSSL but has to be
388 "one.one.one.one" for WolfSSL. The latter works for both, so OK, we'll change
390 - There seems to be some difference in CA databases too - the WolfSSL version
392 that for our purposes via ``--insecure``/``-k`` but would need to fix for a
397 - tweak to ``configure.ac`` to check if WolfSSL has ECH or not
398 - added code to ``lib/vtls/wolfssl.c`` mirroring what's done in the
400 - WolfSSL does not support ``--ech false`` or the ``--ech pn:`` command line
403 The lack of support for ``--ech false`` is because wolfSSL has decided to
405 a compile time choice for wolfSSL, but a runtime choice for OpenSSL or
412 All of the above only applies if DoH is being used. There should be a use-case
413 for ECH when DoH is not used by curl - if a system stub resolver supports DoT
417 on localhost:53, so would fit this use-case. That said, it is unclear if
419 let curl use DoH to talk to the same public recursive that stubby might use:-)
421 Assuming for the moment this is a use-case we'd like to support, then
423 support for ECH. One option would seem to be to extend the ``c-ares`` library
425 would be attractive to the ``c-ares`` maintainers, nor whether the "tag=value"
427 ``c-ares`` approach of defining structures specific to decoded answers for each
429 actually make use of the ``c-ares`` library, which would affect the utility of
436 have some experience with the "using DoH" approach, so we're going to punt on
451 [localhost tests](https://github.com/defo-project/ech-dev-utils/blob/main/howtos/localhost-tests.md)
456 cd $HOME/code/ech-dev-utils
457 ./scripts/echsvr.sh -d
461 The ``echsvr.sh`` script supports many ECH-related options. Use ``echsvr.sh -h``
468 …./src/curl -vvv --insecure --connect-to foo.example.com:8443:localhost:8443 --ech ecl:AD7+DQA6uw…
474 application - for a command line tool, one can just use ``dig`` (or ``kdig``)
477 and then re-use that in another invocation.
480 accessing and logging ``retry_configs``, it seems WolfSSL has neither.