quickjs-tart

quickjs-based runtime for wallet-core logic
Log | Files | Refs | README | LICENSE

CURLOPT_ECH.md (2503B)

      1 ---
      2 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
      3 SPDX-License-Identifier: curl
      4 Title: CURLOPT_ECH
      5 Section: 3
      6 Source: libcurl
      7 See-also:
      8   - CURLOPT_DOH_URL (3)
      9 Protocol:
     10   - TLS
     11 TLS-backend:
     12   - OpenSSL
     13   - wolfSSL
     14   - rustls
     15 Added-in: 8.8.0
     16 ---
     17 
     18 # NAME
     19 
     20 CURLOPT_ECH - configuration for Encrypted Client Hello
     21 
     22 # SYNOPSIS
     23 
     24 ~~~c
     25 #include <curl/curl.h>
     26 
     27 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ECH, char *config);
     28 ~~~
     29 
     30 # DESCRIPTION
     31 
     32 ECH is only compatible with TLSv1.3.
     33 
     34 This experimental feature requires a special build of OpenSSL, as ECH is not
     35 yet supported in OpenSSL releases. In contrast ECH is supported by the latest
     36 BoringSSL, wolfSSL and rustls-ffi releases.
     37 
     38 There is also a known issue with using wolfSSL which does not support ECH when
     39 the HelloRetryRequest mechanism is used.
     40 
     41 Pass a string that specifies configuration details for ECH. In all cases, if
     42 ECH is attempted, it may fail for various reasons. The keywords supported are:
     43 
     44 ## false
     45 
     46 Turns off ECH.
     47 
     48 ## grease
     49 
     50 Instructs client to emit a GREASE ECH extension. (The connection fails if ECH
     51 is attempted but fails.)
     52 
     53 ## true
     54 
     55 Instructs client to attempt ECH, if possible, but to not fail if attempting
     56 ECH is not possible.
     57 
     58 ## hard
     59 
     60 Instructs client to attempt ECH and fail if attempting ECH is not possible.
     61 
     62 ## ecl:\<base64-value\>
     63 
     64 If the string starts with `ecl:` then the remainder of the string should be a
     65 base64-encoded ECHConfigList that is used for ECH rather than attempting to
     66 download such a value from the DNS.
     67 
     68 ## pn:\<name\>
     69 
     70 If the string starts with `pn:` then the remainder of the string should be a
     71 DNS/hostname that is used to over-ride the public_name field of the
     72 ECHConfigList that is used for ECH.
     73 
     74 ##
     75 
     76 The application does not have to keep the string around after setting this
     77 option.
     78 
     79 Using this option multiple times makes the last set string override the
     80 previous ones. Set it to NULL or "false" to disable its use again.
     81 
     82 # DEFAULT
     83 
     84 NULL, meaning ECH is disabled.
     85 
     86 # %PROTOCOLS%
     87 
     88 # EXAMPLE
     89 
     90 ~~~c
     91 int main(void)
     92 {
     93   CURL *curl = curl_easy_init();
     94 
     95   const char *config = \
     96     "ecl:AED+DQA87wAgACB/RuzUCsW3uBbSFI7mzD63TUXpI8sGDTnFTbFCDpa+" \
     97     "CAAEAAEAAQANY292ZXIuZGVmby5pZQAA";
     98   if(curl) {
     99     curl_easy_setopt(curl, CURLOPT_ECH, config);
    100     curl_easy_perform(curl);
    101   }
    102 }
    103 ~~~
    104 # %AVAILABILITY%
    105 
    106 # RETURN VALUE
    107 
    108 curl_easy_setopt(3) returns a CURLcode indicating success or error.
    109 
    110 CURLE_OK (0) means everything was OK, non-zero means an error occurred, see
    111 libcurl-errors(3).