=pod

=head1 NAME

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
- Encrypted Client Hello (ECH) functions

=head1 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);

=head1 DESCRIPTION

The Encrypted Client Hello (ECH) APIs described here are built around
the concept of an B<OSSL_ECHSTORE> which contains ECH configuration
information relevant for an B<SSL_CTX> or B<SSL> connection.

This release only supports ECH shared-mode and has no support for
ECH split-mode.

=head2 OSSL_ECHSTORE APIs

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

OSSL_ECHSTORE_new() and OSSL_ECHSTORE_free() create and free the
internal storage required.

OSSL_ECHSTORE_new_config() allows the caller to create a new private key
value and a related "singleton" ECHConfigList structure.
("Singleton" meaning the ECHConfigList only contains one public key.)
The I<echversion> is the ECHConfig version to use, which is typically
B<OSSL_ECH_CURRENT_VERSION> with a value of 0xfe0d. The I<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 I<public_name> is the DNS name to use in
the ECHConfig I<public_name> field, and the I<suite> specifies the
B<OSSL_HPKE_suite> to use (see L<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 B<OSSL_ECHSTORE> entry
identified by the I<index>. (An I<index> of B<OSSL_ECHSTORE_LAST> will select the
last entry. An I<index> of B<OSSL_ECHSTORE_ALL> will output all public values,
and no private values, otherwise the I<index> selects a specific entry with
zero selecting the first entry.) The output will be written to the I<out>
B<BIO>.

The B<OSSL_ECHSTORE> APIs above will typically be used via the "openssl ech"
command line tool.

OSSL_ECHSTORE_read_echconfiglist() reads from the I<in> B<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 I<es> store, and can then be
associated with an B<SSL_CTX> or B<SSL> structure for TLS client connections.

Input B<BIO> values (such a I<in> above) must not use unterminated B<BIO>'s.

OSSL_ECHSTORE_get1_info() queries the store provided by I<es> and finds the
entry within the store specified by I<index>. The number of seconds since that
entry was first generated or loaded/decoded is stored in I<loaded_secs>, and
the related public name is stored in I<*public_name>. This function also
outputs a string useful for logging or display (as described in the
L</String form of ECHConfig> section) and stores that in I<*echconfig>.  It is
the callers responsibility to free the strings returned in I<public_name> and
I<echconfig> after they have been returned. If the specified entry has a
private key associated with it then I<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 I<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 I<index> from those stored in the
I<es>, discarding the rest. This can be used by a client (via L<openssl-ech(1)>
and L<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 B<BIO> I<in>
into an B<OSSL_ECHSTORE> structure.  The former function pairs a
previously-loaded private key (in B<EVP_PKEY> format) with an associated
base64-encoded ECHConfigList in the I<in> B<BIO>. The latter function reads
both from an ECH PEM file.  Those can be used (by servers) to enable ECH for an
B<SSL_CTX> or B<SSL> connection. In addition to loading those values, the
application can also indicate via I<for_retry> which ECHConfig values are to be
included in the I<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, I<public_name> values, or
AEAD/KDF settings are to be supported. When such a file is read, the resulting
B<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 I<numentries>) and private keys (in
I<numkeys>) are present in the I<es> B<OSSL_ECHSTORE> store.

OSSL_ECHSTORE_flush_keys() allows a server to flush keys from I<es> that were
loaded more than I<age> seconds ago.  The general model is that a server can
maintain an B<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 I<es> (an B<OSSL_ECHSTORE>) with an B<SSL_CTX> or B<SSL> structure.
ECH will be enabled for the relevant B<SSL_CTX> or B<SSL> connection when these
functions succeed. Any previously associated B<OSSL_ECHSTORE> will be freed via
OSSL_ECHSTORE_free(). Internally, B<OSSL_ECHSTORE> values within an B<SSL_CTX>
or B<SSL> connection are deep-copied, and are not refcounted.

SSL_CTX_get1_echstore() and SSL_get1_echstore() provide access to the
B<OSSL_ECHSTORE> associated with an B<SSL_CTX> or B<SSL> connection.  The
returned B<OSSL_ECHSTORE> can be modified and then re-associated with an
B<SSL_CTX> or B<SSL> connection.

=head2 Client ECH Controls

SSL_set1_ech_config_list() allows clients to setup ECH by associating an
ECHConfigList, I<ecl> with an B<SSL> connection I<s>. This is compatible with
current BoringSSL APIs, allowing for smaller code changes for clients that
support OpenSSL or BoringSSL. Note that the input I<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 B<SSL> connection, I<s>.  The I<inner_name>
provided will be used as with L<SSL_set_tlsext_host_name(3)> to populate the
SNI value for the inner ClientHello. The I<outer_name>, if non-NULL, can
over-ride the public_name field of the ECHConfig used for the connection.  The
I<no_outer> input allows a client to emit an outer ClientHello with no SNI at
all. Providing a NULL for the I<outer_name> means to send the I<public_name>
provided from the ECHConfigList unless the I<no_outer> provided has the value
1.

If a client has called L<SSL_CTX_set_alpn_protos(3)> or
L<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 B<SSL> connection, I<s>. The
I<protos> and I<protos_len> inputs must be provided as for
L<SSL_set_alpn_protos(3)>.

If a client attempts ECH but that fails, or sends an ECH-GREASE'd ClientHello,
to an ECH-supporting server, then that server may return a set of ECH
retry-config values that the client could choose to use in a subsequent
connection. The client can detect this situation if SSL_ech_get1_status() for
the B<SSL> connection I<s>, returns a status of B<SSL_ECH_STATUS_GREASE_ECH>,
and can then access the ECH retry config values via SSL_ech_get1_retry_config()
where the I<ec> value returned will contain a binary-encoded ECHConfigList
of length I<eclen>.

If a client makes a real attempt at ECH that fails then the server can also
return retry config values, and those can be used if they were authenticated
under the outer SNI used for the session. In this case the TLS session fails
returning the error B<SSL_R_ECH_REQUIRED>, and the ECH status of
B<SSL_ECH_STATUS_FAILED_ECH> indicates that retry config values can be
accessed using 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.
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.

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

SSL_ech_set1_grease_suite() allows a client to GREASE ECH for the B<SSL>
connection I<s>, using a specific B<OSSL_HPKE_SUITE> as the value for I<suite>
(see L<OSSL_HPKE_get_grease_value(3)>).  SSL_ech_set_grease_type() allows a
client to add a GREASE'd ECH for the B<SSL> connection I<s>, using the
specified ClientHello extension number I<type>.

Clients and servers can query the status of ECH for a B<SSL> connection I<s>,
using the SSL_ech_get1_status() function. As SNI handling is core to ECH this
will also return the I<inner_sni> and I<outer_sni> values to 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.  The various status values returned by this function
are as described in L</Constants>.

=head2 Callback Functions

Applications can set a callback function that will be 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 will happen after the SeverHello has
been processed. In the event of HelloRetryRequest, the callback will
only be triggered when processing the second ServerHello. The callback
function will be triggered even if the client is only GREASEing.

The callback function prototype is:

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

To set a callback function for the B<SSL> connection I<s>, use
SSL_ech_set_callback() or SSL_CTX_ech_set_callback() for a B<SSL_CTX> I<ctx> -
the I<f> input should match the above prototype.

When the callback function is called, the I<str> will point at a string
intended for logging describing the state of ECH processing.
Applications should not attempt to parse that string as 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.

An example string I<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]

=head2 Constants

Some externally visible limits:

=over 4

=item B<OSSL_ECH_MAX_PAYLOAD_LEN> 1500, maximum length of an ECH ciphertext to en/decode

=item B<OSSL_ECH_MIN_ECHCONFIG_LEN> 32, minimum length of an encoded ECHConfig

=item B<OSSL_ECH_MAX_ECHCONFIG_LEN> 1500, maximum length of an encoded ECHConfig

=item B<OSSL_ECH_MAX_ECHCONFIGEXT_LEN> 512, maximum length of an ECHConfig extension

=item B<OSSL_ECH_MAX_MAXNAMELEN> 255, maximum for ECHConfig max name length

=item B<OSSL_ECH_MAX_PUBLICNAME> 255, maximum length of an ECHConfig public name

=item B<OSSL_ECH_MAX_ALPN_LEN> 255, maximum overall length of an ALPN

=item B<OSSL_ECH_OUTERS_MAX> 20, maximum number of extensions compressed via outer-exts

=item B<OSSL_ECH_ALLEXTS_MAX> 32, maximum total number of extensions allowed

=back

ECH version - the only supported version is 0xfe0d currently.

=over 4

=item B<OSSL_ECH_RFC9849_VERSION> 0xfe0d, official ECHConfig version

=item B<OSSL_ECH_CURRENT_VERSION> OSSL_ECH_RFC9849_VERSION

=back

Values for I<for_retry>

=over 4

=item B<SSL_ECH_USE_FOR_RETRY>  1. use corresponding ECHConfig values

=item B<SSL_ECH_NOT_FOR_RETRY>  0. don't use corresponding ECHConfig values

=back

Indexing an OSSL_ECHSTORE

=over 4

=item B<OSSL_ECHSTORE_LAST>, -1 select the last entry in the store

=item B<OSSL_ECHSTORE_ALL>, -2 select all entries in the store, e.g. to print public values

=back

=head2 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 I<version> is 0xfe0d, the
I<config_id> is 0x4d, the I<public_name> is "example.com", there is one
ciphersuite with a I<kem-id> of 0x20, I<kdf-id> is 0x01 and I<aead-id> is 0x02;
the I<public_key> is the hexadecimal string "c1...6e", the I<max-name-length>
is 0x00 and the I<extensions> length is 0x00 as no ECHConfig extensions are
present.

=head1 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:

=over 4

=item B<SSL_ECH_STATUS_BACKEND>    4, ECH backend: saw an ech_is_inner

=item B<SSL_ECH_STATUS_GREASE_ECH> 3, GREASEd and got an ECH in return

=item B<SSL_ECH_STATUS_GREASE>     2, ECH GREASE happened

=item B<SSL_ECH_STATUS_SUCCESS>    1, Success

=item B<SSL_ECH_STATUS_FAILED>     0, Some internal or protocol error

=item B<SSL_ECH_STATUS_BAD_CALL>   -100, Some in/out arguments were NULL

=item B<SSL_ECH_STATUS_NOT_TRIED>  -101, ECH wasn't attempted

=item B<SSL_ECH_STATUS_BAD_NAME>   -102, ECH ok but server or client cert bad

=item B<SSL_ECH_STATUS_NOT_CONFIGURED> -103, ECH wasn't configured

=item B<SSL_ECH_STATUS_FAILED_ECH> -105, We tried, failed and got an ECH, from a verified name

=item B<SSL_ECH_STATUS_FAILED_ECH_BAD_NAME> -106, We tried, failed and got an ECH, from a bad name

=back

SSL_ech_set_callback(), SSL_CTX_ech_set_callback(), OSSL_ECHSTORE_free() have
no return value.

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

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 L<SSL_CTX_set_alpn_protos(3)> and L<SSL_set_alpn_protos(3)>
which (unusually for OpenSSL) return 0 on success and 1 on error.

=head1 SEE ALSO

=over 4

=item Encrypted ClientHello specification: L<https://datatracker.ietf.org/doc/rfc9849>

=item ECH PEM file format specification: L<https://datatracker.ietf.org/doc/rfc9934>

=item RFC8701: L<https://datatracker.ietf.org/doc/rfc8701>

=back

ECH command line options are described in the manual pages for
L<openssl-s_client(1)>, L<openssl-s_server(1)> and L<openssl-ech(1)>.

=head1 HISTORY

The functionality described here was added in OpenSSL 4.0.

=head1 COPYRIGHT

Copyright 2025-2026 The OpenSSL Project Authors. All Rights Reserved.

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
L<https://www.openssl.org/source/license.html>.

=cut