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