Sortix volatile manual

This manual documents Sortix volatile, a development build that has not been officially released. You can instead view this document in the latest official manual.

CURLOPT_ECH(3)

Library Functions Manual

CURLOPT_ECH(3)

NAME

CURLOPT_ECH - 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);
}

AVAILABILITY

Added in curl 8.8.0

RETURN VALUE

Returns CURLE_OK on success or CURLE_OUT_OF_MEMORY if there was insufficient heap space.