2024-06-01 14:49:19 -06:00
|
|
|
.\" generated by cd2nroff 0.1 from CURLOPT_ECH.md
|
2024-08-02 19:52:59 -06:00
|
|
|
.TH CURLOPT_ECH 3 "2024-08-02" libcurl
|
2024-06-01 14:49:19 -06:00
|
|
|
.SH NAME
|
|
|
|
|
CURLOPT_ECH \- configuration for Encrypted Client Hello
|
|
|
|
|
.SH SYNOPSIS
|
|
|
|
|
.nf
|
|
|
|
|
#include <curl/curl.h>
|
|
|
|
|
|
|
|
|
|
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ECH, char *config);
|
|
|
|
|
.fi
|
|
|
|
|
.SH 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:
|
|
|
|
|
.IP false
|
|
|
|
|
Turns off ECH.
|
|
|
|
|
.IP grease
|
|
|
|
|
Instructs client to emit a GREASE ECH extension. (The connection fails if ECH
|
|
|
|
|
is attempted but fails.)
|
|
|
|
|
.IP true
|
|
|
|
|
Instructs client to attempt ECH, if possible, but to not fail if attempting
|
|
|
|
|
ECH is not possible.
|
|
|
|
|
.IP hard
|
2024-07-29 18:00:04 -06:00
|
|
|
Instructs client to attempt ECH and fail if attempting ECH is not possible.
|
2024-06-01 14:49:19 -06:00
|
|
|
.IP ecl:\<base64-value\>
|
|
|
|
|
If the string starts with \fIecl:\fP 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.
|
|
|
|
|
.IP pn:\<name\>
|
|
|
|
|
If the string starts with \fIpn:\fP 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.
|
|
|
|
|
.SH DEFAULT
|
|
|
|
|
NULL, meaning ECH is disabled.
|
|
|
|
|
.SH PROTOCOLS
|
2024-07-29 18:00:04 -06:00
|
|
|
This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc.
|
2024-06-01 14:49:19 -06:00
|
|
|
|
|
|
|
|
This option works only with the following TLS backends:
|
|
|
|
|
OpenSSL and wolfSSL
|
|
|
|
|
.SH EXAMPLE
|
|
|
|
|
.nf
|
|
|
|
|
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);
|
|
|
|
|
}
|
|
|
|
|
.fi
|
|
|
|
|
.SH AVAILABILITY
|
2024-07-29 18:00:04 -06:00
|
|
|
Added in curl 8.8.0
|
2024-06-01 14:49:19 -06:00
|
|
|
.SH RETURN VALUE
|
|
|
|
|
Returns CURLE_OK on success or CURLE_OUT_OF_MEMORY if there was insufficient
|
|
|
|
|
heap space.
|
|
|
|
|
.SH SEE ALSO
|
|
|
|
|
.BR CURLOPT_DOH_URL (3)
|
