SSL_SET1_ECHSTORE(3SSL)

📦

version 4.0.3 · 2 versions

4.0.3 · ubuntu stonking (latest)
4.1.0 · nixos 26.05, nixpkgs unstable

🌸 NAME 🌸

okay so this page is SSL_SET1_ECHSTORE(3SSL) from OpenSSL, and it's giving Encrypted Client Hello (ECH) functions ✨ the whole squad is here: SSL_set1_echstore, OSSL_ECHSTORE_new, OSSL_ECHSTORE_free, OSSL_ECHSTORE_new_config, OSSL_ECHSTORE_write_pem, OSSL_ECHSTORE_read_echconfiglist, OSSL_ECHSTORE_get1_info, OSSL_ECHSTORE_downselect, OSSL_ECHSTORE_set1_key_and_read_pem, OSSL_ECHSTORE_read_pem, OSSL_ECHSTORE_num_entries, OSSL_ECHSTORE_num_keys, OSSL_ECHSTORE_flush_keys, SSL_CTX_set1_echstore, SSL_CTX_get1_echstore, SSL_get1_echstore, SSL_ech_set1_server_names, SSL_ech_set1_outer_server_name, SSL_ech_set1_outer_alpn_protos, SSL_ech_get1_status, SSL_ech_set1_grease_suite, SSL_ech_set_grease_type, SSL_ech_set_callback, SSL_ech_get1_retry_config, SSL_CTX_ech_set1_outer_alpn_protos, SSL_CTX_ech_set_callback, SSL_set1_ech_config_list — all the Encrypted Client Hello (ECH) functions 💅

✨ SYNOPSIS ✨

#include <openssl/ech.h>

OSSL_ECHSTORE *OSSL_ECHSTORE_new(OSSL_LIB_CTX *libctx, const char *propq);
void OSSL_ECHSTORE_free(OSSL_ECHSTORE *es);
int OSSL_ECHSTORE_new_config(OSSL_ECHSTORE *es,
                             uint16_t echversion, uint16_t max_name_length,
                             const char *public_name, OSSL_HPKE_SUITE suite);
int OSSL_ECHSTORE_write_pem(OSSL_ECHSTORE *es, int index, BIO *out);
int OSSL_ECHSTORE_read_echconfiglist(OSSL_ECHSTORE *es, BIO *in);
int OSSL_ECHSTORE_get1_info(OSSL_ECHSTORE *es, int index, time_t *loaded_secs,
                            char **public_name, char **echconfig,
                            int *has_private, int *for_retry);
int OSSL_ECHSTORE_downselect(OSSL_ECHSTORE *es, int index);
int OSSL_ECHSTORE_set1_key_and_read_pem(OSSL_ECHSTORE *es, EVP_PKEY *priv,
                                        BIO *in, int for_retry);
int OSSL_ECHSTORE_read_pem(OSSL_ECHSTORE *es, BIO *in, int for_retry);
int OSSL_ECHSTORE_num_entries(OSSL_ECHSTORE *es, int *numentries);
int OSSL_ECHSTORE_num_keys(OSSL_ECHSTORE *es, int *numkeys);
int OSSL_ECHSTORE_flush_keys(OSSL_ECHSTORE *es, time_t age);
int SSL_CTX_set1_echstore(SSL_CTX *ctx, OSSL_ECHSTORE *es);
int SSL_set1_echstore(SSL *s, OSSL_ECHSTORE *es);
OSSL_ECHSTORE *SSL_CTX_get1_echstore(const SSL_CTX *ctx);
OSSL_ECHSTORE *SSL_get1_echstore(const SSL *s);
int SSL_ech_set1_server_names(SSL *s, const char *inner_name,
                              const char *outer_name, int no_outer);
int SSL_ech_set1_outer_server_name(SSL *s, const char *outer_name, int no_outer);
int SSL_ech_set1_outer_alpn_protos(SSL *s, const unsigned char *protos,
                                   const size_t protos_len);
int SSL_ech_get1_status(SSL *s, char **inner_sni, char **outer_sni);
int SSL_ech_set1_grease_suite(SSL *s, const char *suite);
int SSL_ech_set_grease_type(SSL *s, uint16_t type);
void SSL_ech_set_callback(SSL *s, SSL_ech_cb_func f);
int SSL_ech_get1_retry_config(SSL *s, unsigned char **ec, size_t *eclen);
void SSL_CTX_ech_set_callback(SSL_CTX *ctx, SSL_ech_cb_func f);
int SSL_CTX_ech_set1_outer_alpn_protos(SSL_CTX *ctx,
                                       const unsigned char *protos,
                                       const size_t protos_len);
int SSL_set1_ech_config_list(SSL *ssl, const uint8_t *ecl, size_t ecl_len);

💖 DESCRIPTION 💖

okay so the whole concept: Encrypted Client Hello (ECH) APIs described here are built around the idea of an OSSL_ECHSTORE that holds ECH configuration information relevant for an SSL_CTX or SSL connection. literally the main character of this whole page 💁‍♀️

heads up bestie: this release only supports ECH shared-mode and has no support for ECH split-mode. periodt, that's the limit.

🦋 OSSL_ECHSTORE APIs 🦋

The externally opaque type OSSL_ECHSTORE lets applications create and manage ECHConfigList values, ECH private keys and associated meta-data. The external APIs using OSSL_ECHSTORE are:

OSSL_ECHSTORE_new() and OSSL_ECHSTORE_free() — create and free the internal storage required. 💖
OSSL_ECHSTORE_new_config() — lets the caller create a new private key value and a related "singleton" ECHConfigList structure. ("Singleton" meaning the ECHConfigList only contains one public key.) The echversion is the ECHConfig version to use, which is typically OSSL_ECH_CURRENT_VERSION with a value of 0xfe0d. The max_name_length specifies the maximum known DNS name length that will be present in an ECH extension (if known) and is used for ECH padding but should typically be zero, to indicate no known maximum. The public_name is the DNS name to use in the ECHConfig public_name field, and the suite specifies the OSSL_HPKE_suite to use (see OSSL_HPKE_CTX_new(3) for details.) ✨
OSSL_ECHSTORE_write_pem() — allows the caller to produce an ECH PEM data structure (conforming to the ECH PEM file format) from the OSSL_ECHSTORE entry identified by the index. (An index of OSSL_ECHSTORE_LAST will select the last entry. An index of OSSL_ECHSTORE_ALL will output all public values, and no private values, otherwise the index selects a specific entry with zero selecting the first entry.) The output will be written to the out BIO. 📝
The OSSL_ECHSTORE APIs above will typically be used via the "openssl ech" command line tool. 👑
OSSL_ECHSTORE_read_echconfiglist() — reads from the in BIO and parses a base64-encoded ECHConfigList value normally found in the "ech=" SvcParamKey present in an SVCB or HTTPS RR retrieved from the DNS. The resulting set of ECHConfig values, are associated with the es store, and can then be associated with an SSL_CTX or SSL structure for TLS client connections. 💅
Input BIO values (such as in above) must not use unterminated BIO's. 🚫
OSSL_ECHSTORE_get1_info() — queries the store provided by es and finds the entry within the store specified by index. The number of seconds since that entry was first generated or loaded/decoded is stored in loaded_secs, and the related public name is stored in *public_name. This function also outputs a string useful for logging or display (as described in the "String form of ECHConfig" section) and stores that in *echconfig. It is the callers responsibility to free the strings returned in public_name and echconfig after they have been returned. If the specified entry has a private key associated with it then has_private will be set to 1, otherwise it will be set to 0. Similarly if the ECHConfig for this entry will be included in "retry-configs" then the for_retry will be set to 1 or zero if that ECHConfig will not be included in retry-configs. 👀
The ECH fallback scheme involving retry-configs is described in Section 6.1.1 of RFC 9849. 📖
OSSL_ECHSTORE_downselect() — provides the caller a way to select one particular ECHConfig value based on the zero-based index from those stored in the es, discarding the rest. This can be used by a client (via openssl-ech(1) and openssl-s_client(1) or equivalent) to pick a specific ECHConfig to use in a TLS connection. 🎯
OSSL_ECHSTORE_set1_key_and_read_pem() and OSSL_ECHSTORE_read_pem() — can be used to load a private key value and associated ECHConfigList from the BIO in into an OSSL_ECHSTORE structure. The former function pairs a previously-loaded private key (in EVP_PKEY format) with an associated base64-encoded ECHConfigList in the in BIO. The latter function reads both from an ECH PEM file. Those can be used (by servers) to enable ECH for an SSL_CTX or SSL connection. In addition to loading those values, the application can also indicate via for_retry which ECHConfig values are to be included in the retry_configs fallback scheme defined by the ECH protocol. 🔐
An ECH PEM file may contain a private key and an ECHConfigList with more than one ECHConfig, for example if different public keys, public_name values, or AEAD/KDF settings are to be supported. When such a file is read, the resulting OSSL_ECHSTORE will contain one entry for each ECHConfig in the ECHConfigList, so will be presented to applications as a set of "singleton" ECHConfig values, with the private key associated with each matching public key value. 🧚
OSSL_ECHSTORE_num_entries() and OSSL_ECHSTORE_num_keys() — allow an application to see how many ECH configs (in numentries) and private keys (in numkeys) are present in the es OSSL_ECHSTORE store. 🔢
OSSL_ECHSTORE_flush_keys() — allows a server to flush keys from es that were loaded more than age seconds ago. The general model is that a server can maintain an OSSL_ECHSTORE into which it periodically loads the "latest" set of keys, e.g. hourly, and also discards the keys that are too old, e.g. more than 3 hours old. This allows for more robust private key management even if public key distribution suffers temporary failures. 🕰️
SSL_CTX_set1_echstore() and SSL_set1_echstore() — allow clients and servers to associate es (an OSSL_ECHSTORE) with an SSL_CTX or SSL structure. ECH will be enabled for the relevant SSL_CTX or SSL connection when these functions succeed. Any previously associated OSSL_ECHSTORE will be freed via OSSL_ECHSTORE_free(). Internally, OSSL_ECHSTORE values within an SSL_CTX or SSL connection are deep-copied, and are not refcounted. 🫶
SSL_CTX_get1_echstore() and SSL_get1_echstore() — provide access to the OSSL_ECHSTORE associated with an SSL_CTX or SSL connection. The returned OSSL_ECHSTORE can be modified and then re-associated with an SSL_CTX or SSL connection. 🔑

💅 Client ECH Controls 💅

SSL_set1_ech_config_list() — allows clients to setup ECH by associating an ECHConfigList, ecl with an SSL connection s. This is compatible with current BoringSSL APIs, allowing for smaller code changes for clients that support OpenSSL or BoringSSL. Note that the input ecl here for OpenSSL can be either base64 or binary encoded, but for BoringSSL it must be binary encoded. 😮
SSL_ech_set1_server_names() and SSL_ech_set1_outer_server_name() — allow clients to more directly control the values to be used for inner and outer Server Name Indication (SNI) values for an SSL connection, s. The inner_name provided will be used as with SSL_set_tlsext_host_name(3) to populate the SNI value for the inner ClientHello. The outer_name, if non-NULL, can over-ride the public_name field of the ECHConfig used for the connection. The no_outer input allows a client to emit an outer ClientHello with no SNI at all. Providing a NULL for the outer_name means to send the public_name provided from the ECHConfigList unless the no_outer provided has the value 1. 🌈
If a client has called SSL_CTX_set_alpn_protos(3) or SSL_set_alpn_protos(3) then the ALPN value will be the same in the inner and outer ClientHello messages. SSL_ech_set1_outer_alpn_protos() and SSL_CTX_ech_set1_outer_alpn_protos() allow clients to set a specific value for the ALPN sent in the outer ClientHello of the SSL connection, s. The protos and protos_len inputs must be provided as for SSL_set_alpn_protos(3). 🎀

So if a client attempts ECH but it fails, or it sends an ECH-GREASE'd ClientHello to a server that does support ECH, then that server might hit the client back with a set of ECH retry-config values that the client could lowkey choose to use in a later connection. The client can spot this whole situation if SSL_ech_get1_status() for the SSL connection s returns a status of SSL_ECH_STATUS_GREASE_ECH, and then it can grab the ECH retry config values via SSL_ech_get1_retry_config() — and the ec value it hands back will contain a binary-encoded ECHConfigList of length eclen. bestie that's the tea 🫖

Now if a client makes a real attempt at ECH and it flops, the server can also return retry config values, and those are usable if they were authenticated under the outer SNI used for the session. In this case the TLS session fails, returning the error SSL_R_ECH_REQUIRED, and the ECH status of SSL_ECH_STATUS_FAILED_ECH is basically the server saying "retry config values are available, come get them" via SSL_ech_get1_retry_config(). The application can then choose to use those in a subsequent attempt to establish a TLS session with the server. But if the TLS session fails for some other reason (e.g. a bad server Finished message), then the retry config values will not be returned to the application. no crumbs left, sorry 😭

"GREASEing" (defined in RFC8701) is a mechanism intended to discourage protocol ossification that can be used for ECH. slay for anti-ossification 💅

SSL_ech_set1_grease_suite() — lets a client GREASE ECH for the SSL connection s, using a specific OSSL_HPKE_SUITE as the value for suite (see OSSL_HPKE_get_grease_value(3)).
SSL_ech_set_grease_type() — lets a client add a GREASE'd ECH for the SSL connection s, using the specified ClientHello extension number type.

Clients and servers can query the status of ECH for an SSL connection s using the SSL_ech_get1_status() function. And since SNI handling is core to ECH, this will also return the inner_sni and outer_sni values that are gonna be used (or that were used) as well as a status code as the return value. These name values must be freed by the caller — yes, you, bestie, that's on you 🫶. The various status values this function returns are all described down in "Constants".

🎀 Callback Functions 🎀

Applications can set a callback function that gets called when the outcome from an attempt at ECH has been determined. On the server, that happens early, as part of construction of the ServerHello message. On the client, the callback happens after the ServerHello has been processed. And in the event of HelloRetryRequest, the callback only gets triggered when processing the second ServerHello. The callback function will be triggered even if the client is only GREASEing. periodt 💅

The callback function prototype is:

typedef unsigned int (*SSL_ech_cb_func)(SSL *s, const char *str);

To set a callback function for the SSL connection s, use SSL_ech_set_callback() or SSL_CTX_ech_set_callback() for a SSL_CTX ctx — the f input should match the above prototype. matching game, but make it C ✨

When the callback function is called, the str will point at a string intended for logging that describes the state of ECH processing. Applications should NOT attempt to parse that string, because the value depends on compile time settings, local configuration and the specific processing that happened prior to the callback. Applications that need to branch based on the outcome of ECH processing should instead make a call to SSL_ech_get1_status() from within their callback function. iykyk 🔥

An example string str as seen on a client might be:

ech_attempted=1
ech_attempted_type=0xfe0d
ech_atttempted_cid=0x5d
ech_done=1
ech_grease=0
ech_returned_len=0
ech_backend=0
ech_success=1
2 ECHConfig values loaded
cfg(0): [fe0d,5d,cover.defo.ie,[0020,0001,0001],190984309c1a24cb944c005eb79d9c72ca9a4a979194b553dfd0bffc6b5c152d,00,00]
cfg(1): [fe0d,fd,cover.defo.ie,[0020,0001,0001],46dd4e2c81bb15ef9d194c99b86983844e2a1387e4fb7e7d3b8d368c8e1b4d2a,00,00]

💜 Constants 💜

Some externally visible limits:

OSSL_ECH_MAX_PAYLOAD_LEN 1500 — maximum length of an ECH ciphertext to en/decode
OSSL_ECH_MIN_ECHCONFIG_LEN 32 — minimum length of an encoded ECHConfig
OSSL_ECH_MAX_ECHCONFIG_LEN 1500 — maximum length of an encoded ECHConfig
OSSL_ECH_MAX_ECHCONFIGEXT_LEN 512 — maximum length of an ECHConfig extension
OSSL_ECH_MAX_MAXNAMELEN 255 — maximum for ECHConfig max name length
OSSL_ECH_MAX_PUBLICNAME 255 — maximum length of an ECHConfig public name
OSSL_ECH_MAX_ALPN_LEN 255 — maximum overall length of an ALPN
OSSL_ECH_OUTERS_MAX 20 — maximum number of extensions compressed via outer-exts
OSSL_ECH_ALLEXTS_MAX 32 — maximum total number of extensions allowed

ECH version — the only supported version is 0xfe0d currently. one version ate and left no crumbs 👑

OSSL_ECH_RFC9849_VERSION 0xfe0d — official ECHConfig version
OSSL_ECH_CURRENT_VERSION OSSL_ECH_RFC9849_VERSION

Values for for_retry

SSL_ECH_USE_FOR_RETRY 1 — use corresponding ECHConfig values
SSL_ECH_NOT_FOR_RETRY 0 — don't use corresponding ECHConfig values

Indexing an OSSL_ECHSTORE

OSSL_ECHSTORE_LAST, -1 — select the last entry in the store
OSSL_ECHSTORE_ALL, -2 — select all entries in the store, e.g. to print public values

🌈 String form of ECHConfig 🌈

OSSL_ECHSTORE_get1_info() returns the string form of the ECH public name plus a string describing the content of the ECHConfig, for example:

[fe0d,4d,example.com,[0020,0001,0002],c103d20dddce9b4445829bf01f5b533b728bfa0ebe3a97da33574bc096bb846e,00,00]

In the order presented in the example above: the version is 0xfe0d, the config_id is 0x4d, the public_name is "example.com", there is one ciphersuite with a kem-id of 0x20, kdf-id is 0x01 and aead-id is 0x02; the public_key is the hexadecimal string "c1...6e", the max-name-length is 0x00 and the extensions length is 0x00 since no ECHConfig extensions are present. decode the vibe, slay 🔍✨

✨ RETURN VALUES ✨

SSL_set1_echstore(), SSL_set1_ech_config_list(), OSSL_ECHSTORE_new_config(), OSSL_ECHSTORE_write_pem(), OSSL_ECHSTORE_read_echconfiglist(), OSSL_ECHSTORE_get1_info(), OSSL_ECHSTORE_downselect(), OSSL_ECHSTORE_set1_key_and_read_pem(), OSSL_ECHSTORE_read_pem(), OSSL_ECHSTORE_num_keys(), OSSL_ECHSTORE_num_entries(), OSSL_ECHSTORE_flush_keys(), SSL_CTX_set1_echstore(), SSL_ech_set_server_names(), SSL_ech_set_outer_server_name(), SSL_ech_set_outer_alpn_protos(), SSL_ech_set_grease_suite(), SSL_ech_set_grease_type(), SSL_ech_get_retry_config() and SSL_CTX_ech_set1_outer_alpn_protos() all return zero on error and one on success.

SSL_ech_get1_status() returns one of the following values:

SSL_ECH_STATUS_BACKEND 4 — ECH backend: saw an ech_is_inner
SSL_ECH_STATUS_GREASE_ECH 3 — GREASEd and got an ECH in return
SSL_ECH_STATUS_GREASE 2 — ECH GREASE happened
SSL_ECH_STATUS_SUCCESS 1 — Success
SSL_ECH_STATUS_FAILED 0 — Some internal or protocol error
SSL_ECH_STATUS_BAD_CALL -100 — Some in/out arguments were NULL
SSL_ECH_STATUS_NOT_TRIED -101 — ECH wasn't attempted
SSL_ECH_STATUS_BAD_NAME -102 — ECH ok but server or client cert bad
SSL_ECH_STATUS_NOT_CONFIGURED -103 — ECH wasn't configured
SSL_ECH_STATUS_FAILED_ECH -105 — We tried, failed and got an ECH, from a verified name
SSL_ECH_STATUS_FAILED_ECH_BAD_NAME -106 — We tried, failed and got an ECH, from a bad name

SSL_ech_set_callback(), SSL_CTX_ech_set_callback() and OSSL_ECHSTORE_free() have no return value. they just do their thing and dip 🦋

SSL_CTX_get1_echstore(), SSL_get1_echstore() and OSSL_ECHSTORE_new() return a pointer to an <cyan>OSSL_ECHSTORE</cyan>.

⚠️ bestie listen — note that SSL_CTX_ech_set1_outer_alpn_protos() and SSL_ech_set1_outer_alpn_protos() return zero on error and 1 on success. This is in contrast to SSL_CTX_set_alpn_protos(3) and SSL_set_alpn_protos(3) which (unusually for OpenSSL) return 0 on success and 1 on error. yeah the polarity is flipped, don't get got 💀

🦋 SEE ALSO 🦋

Encrypted ClientHello specification: <https://datatracker.ietf.org/doc/rfc9849>
ECH PEM file format specification: <https://datatracker.ietf.org/doc/rfc9934>
RFC8701: <https://datatracker.ietf.org/doc/rfc8701>

ECH command line options are described in the manual pages for openssl-s_client(1), openssl-s_server(1) and openssl-ech(1). go read the whole fam 📚

👑 HISTORY 👑

The functionality described here was added in OpenSSL 4.0. new era unlocked ⭐

💖 COPYRIGHT 💖

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.

and that's the whole page bestie, you made it to the end 🎉 this was version 4.0.3 of the manual, dated 2026-09-29 — go forth and ECH responsibly 💅🌸💖

📦 where this page comes from

ubuntu stonking: libssl-doc 4.0.3-1ubuntu1 · Apache-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms