CURLOPT_ECH - Man Page

configuration for Encrypted Client Hello

Synopsis

#include <curl/curl.h>

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ECH, char *config);

Description

ECH is only compatible with TLSv1.3.

This experimental feature requires a special build of OpenSSL, as ECH is not yet supported in OpenSSL releases. In contrast ECH is supported by the latest BoringSSL and wolfSSL releases.

There is also a known issue with using wolfSSL which does not support ECH when the HelloRetryRequest mechanism is used.

Pass a string that specifies configuration details for ECH. In all cases, if ECH is attempted, it may fail for various reasons. The keywords supported are:

false: Turns off ECH.
grease: Instructs client to emit a GREASE ECH extension. (The connection fails if ECH is attempted but fails.)
true: Instructs client to attempt ECH, if possible, but to not fail if attempting ECH is not possible.
hard: Instructs client to attempt ECH and fail if attempting ECH is not possible.
ecl:<base64-value>: If the string starts with ecl: then the remainder of the string should be a base64-encoded ECHConfigList that is used for ECH rather than attempting to download such a value from the DNS.
pn:<name>: If the string starts with pn: then the remainder of the string should be a DNS/hostname that is used to over-ride the public_name field of the ECHConfigList that is used for ECH.

Default

NULL, meaning ECH is disabled.

Protocols

This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc.

This option works only with the following TLS backends: OpenSSL and wolfSSL

Example

CURL *curl = curl_easy_init();

const char *config ="ecl:AED+DQA87wAgACB/RuzUCsW3uBbSFI7mzD63TUXpI8sGDTnFTbFCDpa+CAAEAAEAAQANY292ZXIuZGVmby5pZQAA";
if(curl) {
  curl_easy_setopt(curl, CURLOPT_ECH, config);
  curl_easy_perform(curl);
}