[PATCH] Documented ssl_encrypted_hello_key and $ssl_encrypted_hello
Maxim Dounin
mdounin at mdounin.ru
Sun Sep 21 01:47:09 UTC 2025
# HG changeset patch
# User Maxim Dounin <mdounin at mdounin.ru>
# Date 1758418849 -10800
# Sun Sep 21 04:40:49 2025 +0300
# Node ID 2ed65baa79a5665c4269f7e846d9fd709d3359b8
# Parent be65dd520e819e2ea78516e64f8a47be6defae10
Documented ssl_encrypted_hello_key and $ssl_encrypted_hello.
diff --git a/xml/en/docs/http/ngx_http_ssl_module.xml b/xml/en/docs/http/ngx_http_ssl_module.xml
--- a/xml/en/docs/http/ngx_http_ssl_module.xml
+++ b/xml/en/docs/http/ngx_http_ssl_module.xml
@@ -10,7 +10,7 @@
<module name="Module ngx_http_ssl_module"
link="/en/docs/http/ngx_http_ssl_module.html"
lang="en"
- rev="64">
+ rev="65">
<section id="summary">
@@ -448,6 +448,87 @@ it is important to include the curves us
</directive>
+<directive name="ssl_encrypted_hello_key">
+<syntax><value>file</value></syntax>
+<default/>
+<context>http</context>
+<context>server</context>
+<appeared-in>1.29.2</appeared-in>
+
+<para>
+Specifies a <value>file</value> with a secret key and a configuration
+for the
+<link url="https://datatracker.ietf.org/doc/html/draft-ietf-tls-esni">Encrypted
+Client Hello (ECH)</link> TLS extension.
+The <link id="var_ssl_encrypted_hello">$ssl_encrypted_hello</link> variable
+indicates whether the extension was used during the handshake.
+</para>
+
+<para>
+If several keys are specified,
+all keys are used for decryption,
+and only the configuration corresponding to the first key
+is provided to clients for retries.
+This allows configuring key rotation, for example:
+<example>
+ssl_encrypted_hello_key current.ech;
+ssl_encrypted_hello_key previous.ech;
+</example>
+</para>
+
+<para>
+The <value>file</value> must contain a private key and a configuration
+in the
+<link url="https://datatracker.ietf.org/doc/html/draft-farrell-tls-pemesni">PEM
+format</link>,
+and can be generated with the following command when using the
+<link url="https://github.com/openssl/openssl/tree/feature/ech">OpenSSL
+ECH feature branch</link>:
+<example>
+openssl ech -public_name public.example.com -out example.ech
+</example>
+Alternatively,
+“<command>bssl generate-ech</command>” from BoringSSL can be used,
+but conversion will be needed, for example:
+<example>
+bssl generate-ech \
+ -out-ech-config example.echconfig.bin \
+ -out-ech-config-list example.echconfiglist.bin \
+ -out-private-key example.echkey.bin \
+ -config-id 0 \
+ -public-name public.example.com
+(echo "-----BEGIN PRIVATE KEY-----";
+ (printf "\060\056\002\001\000\060\005\006\003\053\145\156\004\042\004\040";
+ cat example.echkey.bin) | openssl base64;
+ echo "-----END PRIVATE KEY-----";
+ echo "-----BEGIN ECHCONFIG-----";
+ cat example.echconfiglist.bin | openssl base64;
+ echo "-----END ECHCONFIG-----") > example.ech
+</example>
+</para>
+
+<para>
+Decryption occurs before
+the server name requested by the client is known,
+and therefore
+keys should be specified for the default server
+if the directive is used
+on the <link doc="ngx_http_core_module.xml" id="server"/> level.
+See
+“<link doc="server_names.xml" id="virtual_server_selection">Virtual
+server selection</link>” section for details.
+</para>
+
+<para>
+The directive is supported when using the
+<link url="https://github.com/openssl/openssl/tree/feature/ech">OpenSSL
+ECH feature branch</link> or
+<link url="https://boringssl.googlesource.com/boringssl/">BoringSSL</link>.
+</para>
+
+</directive>
+
+
<directive name="ssl_ocsp">
<syntax><literal>on</literal> |
<literal>off</literal> |
@@ -1176,6 +1257,13 @@ TLS 1.3 <link id="ssl_early_data">early
and the handshake is not complete, otherwise “” (1.15.3).
</tag-desc>
+<tag-name id="var_ssl_encrypted_hello"><var>$ssl_encrypted_hello</var></tag-name>
+<tag-desc>
+returns “<literal>1</literal>” if
+the <link id="ssl_encrypted_hello_key">Encrypted Client Hello (ECH)</link>
+TLS extension was used during the handshake, otherwise “” (1.29.2).
+</tag-desc>
+
<tag-name id="var_ssl_protocol"><var>$ssl_protocol</var></tag-name>
<tag-desc>
returns the protocol of an established SSL connection;
diff --git a/xml/ru/docs/http/ngx_http_ssl_module.xml b/xml/ru/docs/http/ngx_http_ssl_module.xml
--- a/xml/ru/docs/http/ngx_http_ssl_module.xml
+++ b/xml/ru/docs/http/ngx_http_ssl_module.xml
@@ -10,7 +10,7 @@
<module name="Модуль ngx_http_ssl_module"
link="/ru/docs/http/ngx_http_ssl_module.html"
lang="ru"
- rev="64">
+ rev="65">
<section id="summary">
@@ -451,6 +451,86 @@ ssl_ecdh_curve prime256v1:secp384r1;
</directive>
+<directive name="ssl_encrypted_hello_key">
+<syntax><value>файл</value></syntax>
+<default/>
+<context>http</context>
+<context>server</context>
+<appeared-in>1.29.2</appeared-in>
+
+<para>
+Задаёт <value>файл</value> с секретным ключом и конфигурацией
+для расширения
+<link url="https://datatracker.ietf.org/doc/html/draft-ietf-tls-esni">Encrypted
+Client Hello (ECH)</link> протокола TLS.
+Переменная <link id="var_ssl_encrypted_hello">$ssl_encrypted_hello</link>
+показывает, использовалось ли расширение при установлении соединения.
+</para>
+
+<para>
+Если указано несколько ключей,
+то все ключи будут использоваться для расшифровки,
+и только конфигурация, соответствующая первому ключу,
+будет передаваться клиентам для повторных попыток соединения.
+Это позволяет настроить ротацию ключей, например:
+<example>
+ssl_encrypted_hello_key current.ech;
+ssl_encrypted_hello_key previous.ech;
+</example>
+</para>
+
+<para>
+<value>Файл</value> должен содержать секретный ключ и конфигурацию в
+<link url="https://datatracker.ietf.org/doc/html/draft-farrell-tls-pemesni"
+>формате PEM</link>
+и, при использовании
+<link url="https://github.com/openssl/openssl/tree/feature/ech">OpenSSL
+ECH feature branch</link>,
+может быть создан следующей командой:
+<example>
+openssl ech -public_name public.example.com -out example.ech
+</example>
+Также
+можно использовать “<command>bssl generate-ech</command>” из BoringSSL,
+но потребуется конвертация, например:
+<example>
+bssl generate-ech \
+ -out-ech-config example.echconfig.bin \
+ -out-ech-config-list example.echconfiglist.bin \
+ -out-private-key example.echkey.bin \
+ -config-id 0 \
+ -public-name public.example.com
+(echo "-----BEGIN PRIVATE KEY-----";
+ (printf "\060\056\002\001\000\060\005\006\003\053\145\156\004\042\004\040";
+ cat example.echkey.bin) | openssl base64;
+ echo "-----END PRIVATE KEY-----";
+ echo "-----BEGIN ECHCONFIG-----";
+ cat example.echconfiglist.bin | openssl base64;
+ echo "-----END ECHCONFIG-----") > example.ech
+</example>
+</para>
+
+<para>
+Расшифровка происходит до того, как
+имя сервера, запрошенное клиентом, становится известно,
+поэтому, если директива используется
+на уровне <link doc="ngx_http_core_module.xml" id="server"/>,
+ключи необходимо указывать для сервера по умолчанию.
+Подробнее см. в разделе
+“<link doc="server_names.xml" id="virtual_server_selection">Выбор
+виртуального сервера</link>”.
+</para>
+
+<para>
+Директива поддерживается при использовании
+<link url="https://github.com/openssl/openssl/tree/feature/ech">OpenSSL
+ECH feature branch</link> или
+<link url="https://boringssl.googlesource.com/boringssl/">BoringSSL</link>.
+</para>
+
+</directive>
+
+
<directive name="ssl_ocsp">
<syntax><literal>on</literal> |
<literal>off</literal> |
@@ -1183,6 +1263,14 @@ 0x001d:prime256v1:secp521r1:secp384r1
и операция handshake не завершена, иначе “” (1.15.3).
</tag-desc>
+<tag-name id="var_ssl_encrypted_hello"><var>$ssl_encrypted_hello</var></tag-name>
+<tag-desc>
+возвращает “<literal>1</literal>”, если
+при установлении соединения использовалось расширение
+<link id="ssl_encrypted_hello_key">Encrypted Client Hello (ECH)</link>
+протокола TLS, иначе “” (1.29.2).
+</tag-desc>
+
<tag-name id="var_ssl_protocol"><var>$ssl_protocol</var></tag-name>
<tag-desc>
возвращает протокол установленного SSL-соединения;
More information about the nginx-devel
mailing list