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 from the command line. This works with OpenSSL, wolfSSL, BoringSSL or AWS-LC as
16 This should however provide enough of a proof-of-concept to prompt an informed
21 To build our ECH-enabled OpenSSL fork:
25 git clone https://github.com/defo-project/openssl
27 ./config --libdir=lib --prefix=$HOME/code/openssl-local-inst
29 make -j8
35 To build curl ECH-enabled, making use of the above:
41 autoreconf -fi
42 …LDFLAGS="-Wl,-rpath,$HOME/code/openssl-local-inst/lib/" ./configure --with-ssl=$HOME/code/openssl-…
50 ECH is not enabled, so go back some steps and re-do whatever needs re-doing:-)
51 If you want to debug curl then you should add ``--enable-debug`` to the
54 In a recent (2024-05-20) build on one machine, configure failed to find the
55 ECH-enabled SSL library, apparently due to the existence of
56 ``$HOME/code/openssl-local-inst/lib/pkgconfig`` as a directory containing
67 …ARY_PATH=$HOME/code/openssl ./src/curl --ech true --doh-url https://one.one.one.one/dns-query http…
69 SSL_ECH_STATUS: success <img src="greentick-small.png" alt="good" /> <br/>
78 https://defo.ie/ech-check.php
79 https://draft-13.esni.defo.ie:8413/stats
80 https://draft-13.esni.defo.ie:8414/stats
81 https://crypto.cloudflare.com/cdn-cgi/trace
82 https://tls-ech.dev
91 - ``--ech <config>`` - the ``config`` value can be one of:
92 - ``false`` says to not attempt ECH
93 - ``true`` says to attempt ECH, if possible
94 - ``grease`` if attempting ECH is not possible, then send a GREASE ECH extension
95 - ``hard`` hard-fail the connection if ECH cannot be attempted
96 - ``ecl:<b64value>`` a base64 encoded ECHConfigList, rather than one accessed from the DNS
97 - ``pn:<name>`` override the ``public_name`` from an ECHConfigList
100 ClientHello with a "real" ECH extension, but that does not mean that the
107 cut-and-paste, e.g.:
117 …enssl ./src/curl --ech ecl:AED+DQA8PAAgACD8WhlS7VwEt5bf3lekhHvXrQBGDrZh03n/LsNtAodbUAAEAAEAAQANY29…
119 SSL_ECH_STATUS: success <img src="greentick-small.png" alt="good" /> <br/>
129 …sl ./src/curl -vvv --ech ecl:AED+DQA8yAAgACDRMQo+qYNsNRNj+vfuQfFIkrrUFmM4vogucxKj/4nzYgAEAAEAAQANY…
135 There is a reason to want this command line option - for use before publishing
136 an ECHConfigList in the DNS as per the Internet-draft [A well-known URI for
137 publishing ECHConfigList values](https://datatracker.ietf.org/doc/draft-ietf-tls-wkech/).
144 …sl ./src/curl -vvv --ech ecl:AED+DQA8yAAgACDRMQo+qYNsNRNj+vfuQfFIkrrUFmM4vogucxKj/4nzYgAEAAEAAQANY…
152 For now, this only works for the OpenSSL and BoringSSL/AWS-LC builds.
161 doh-url=https://one.one.one.one/dns-query
166 Note that when you use the system's curl command (rather than our ECH-enabled
168 issue (e.g. if some script re-directs stdout and stderr somewhere) then adding
170 course, yet another script could depend on non-silent behavior, so you may have
171 to figure out what you prefer yourself.) That seems to have changed with the
192 With all that setup as above the command line gets simpler:
195 ./src/curl https://defo.ie/ech-check.php
197 SSL_ECH_STATUS: success <img src="greentick-small.png" alt="good" /> <br/>
201 The ``--ech true`` option is opportunistic, so tries to do ECH but does not fail if
202 the client for example cannot find any ECHConfig values. The ``--ech hard``
203 option hard-fails if there is no ECHConfig found in DNS, so for now, that is not
211 - ``USE_HTTPSRR`` is used for HTTPS RR retrieval code that could be generically
212 used should non-ECH uses for HTTPS RRs be identified, e.g. use of ALPN values
215 - ``USE_ECH`` protects ECH specific code.
224 determined :-)
229 purpose. This code also implements the opportunistic (``--ech true``) or hard-fail
230 (``--ech hard``) logic.
250 - We could easily add code to make use of an ``alpn=`` value found in an HTTPS
256 - Only the first HTTPS RR value retrieved is actually processed as described
258 could be non-trivial if multiple RRs are published - matching IP address hints
261 needs re-checking as it has been a while.
263 - It is unclear how one should handle any IP address hints found in an HTTPS RR.
264 It may be that a bit of consideration of how "multi-CDN" deployments might
268 - The SVCB/HTTPS RR specification supports a new "CNAME at apex" indirection
269 ("aliasMode") - the current code takes no account of that at all. One could
275 - We have not investigated what related changes or additions might be needed
279 - We have not yet implemented tests as part of the usual curl test harness as
280 doing so would seem to require re-implementing an ECH-enabled server as part
282 that attempts ECH with various test servers and with many combinations of the
289 ## Building with cmake
291 To build with cmake, assuming our ECH-enabled OpenSSL is as before:
299 cmake -DOPENSSL_ROOT_DIR=$HOME/code/openssl -DUSE_ECH=1 ..
306 The binary produced by the cmake build does not need any ECH-specific
312 with that, instead of our ECH-enabled OpenSSL:
318 cmake -DCMAKE_INSTALL_PREFIX:PATH=$HOME/code/boringssl/inst -DBUILD_SHARED_LIBS=1
330 autoreconf -fi
331 …LDFLAGS="-Wl,-rpath,$HOME/code/boringssl/inst/lib" ./configure --with-ssl=$HOME/code/boringssl/ins…
333 WARNING: ECH HTTPSRR enabled but marked EXPERIMENTAL. Use with caution.
337 The BoringSSL/AWS-LC APIs are fairly similar to those in our ECH-enabled
341 The BoringSSL/AWS-LC APIs however do not support the ``--ech pn:`` command
344 ## wolfSSL build
346 wolfSSL also supports ECH and can be used by curl, so here's how:
350 git clone https://github.com/wolfSSL/wolfssl
351 cd wolfssl
353 ./configure --prefix=$HOME/code/wolfssl/inst --enable-ech --enable-debug --enable-opensslextra
358 The install prefix (``inst``) in the above causes wolfSSL to be installed there
360 ``--enable-opensslextra`` turns out (after much faffing about;-) to be
361 important or else we get build problems with curl below.
367 autoreconf -fi
368 ./configure --with-wolfssl=$HOME/code/wolfssl/inst --enable-ech
372 There are some known issues with the ECH implementation in wolfSSL:
374 - The main issue is that the client currently handles HelloRetryRequest
375 incorrectly. [HRR issue](https://github.com/wolfSSL/wolfssl/issues/6802).)
377 [this ECH test web site](https://tls-ech.dev) and any other similarly configured
379 - There is also an issue related to so-called middlebox compatibility mode.
380 [middlebox compatibility issue](https://github.com/wolfSSL/wolfssl/issues/6774)
382 ### Code changes to support wolfSSL
386 - The DoH URL in``$HOME/.curlrc`` can use `1.1.1.1` for OpenSSL but has to be
387 `one.one.one.one` for wolfSSL. The latter works for both, so OK, we us that.
388 - There seems to be some difference in CA databases too - the wolfSSL version
390 ignore that for our purposes via ``--insecure``/``-k`` but would need to fix
395 - tweak to ``configure.ac`` to check if wolfSSL has ECH or not
396 - added code to ``lib/vtls/wolfssl.c`` mirroring what's done in the
398 - wolfSSL does not support ``--ech false`` or the ``--ech pn:`` command line
401 The lack of support for ``--ech false`` is because wolfSSL has decided to
403 a compile time choice for wolfSSL, but a runtime choice for OpenSSL or
404 BoringSSL/AWS-LC. (Both are reasonable.)
410 All of the above only applies if DoH is being used. There should be a use-case
411 for ECH when DoH is not used by curl - if a system stub resolver supports DoT
415 on localhost:53, so would fit this use-case. That said, it is unclear if
417 let curl use DoH to talk to the same public recursive that stubby might use:-)
419 Assuming for the moment this is a use-case we would like to support, then if
421 support for ECH. One option would seem to be to extend the ``c-ares`` library
423 changes would be attractive to the ``c-ares`` maintainers, nor whether the
425 match for the ``c-ares`` approach of defining structures specific to decoded
427 curl deployments actually make use of the ``c-ares`` library, which would
434 have some experience with the "using DoH" approach, so we are going to punt on
449 [localhost tests](https://github.com/defo-project/ech-dev-utils/blob/main/howtos/localhost-tests.md)
454 cd $HOME/code/ech-dev-utils
455 ./scripts/echsvr.sh -d
459 The ``echsvr.sh`` script supports many ECH-related options. Use ``echsvr.sh -h``
466 …./src/curl -vvv --insecure --connect-to foo.example.com:8443:localhost:8443 --ech ecl:AD7+DQA6uw…
472 application - for a command line tool, one can just use ``dig`` (or ``kdig``)
477 Both our OpenSSL fork and BoringSSL/AWS-LC have APIs for both controlling GREASE
478 and accessing and logging ``retry_configs``, it seems wolfSSL has neither.