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