From dc55740d99c078b15dbf332e5663780aebc3af59 Mon Sep 17 00:00:00 2001
From: Vadim Zhestikov <v.zhestikov@f5.com>
Date: Thu, 6 Aug 2026 12:57:25 -0700
Subject: [PATCH] Documented restricting $ssl_server_name used in certificate
 file names

When a variable such as $ssl_server_name -- which holds the unvalidated
name requested by the client -- is used directly in the ssl_certificate
or ssl_certificate_key file name, the client can influence which file is
loaded, for example via a name containing a path separator or "../".

Added a note recommending that the value be restricted to an expected
set of names, for example with the map directive.
---
 xml/en/docs/http/ngx_http_ssl_module.xml     | 26 +++++++++++++++++---
 xml/en/docs/stream/ngx_stream_ssl_module.xml | 26 +++++++++++++++++---
 xml/ru/docs/http/ngx_http_ssl_module.xml     | 26 +++++++++++++++++---
 xml/ru/docs/stream/ngx_stream_ssl_module.xml | 26 +++++++++++++++++---
 4 files changed, 92 insertions(+), 12 deletions(-)

diff --git a/xml/en/docs/http/ngx_http_ssl_module.xml b/xml/en/docs/http/ngx_http_ssl_module.xml
index 0849b207..592ba4c5 100644
--- a/xml/en/docs/http/ngx_http_ssl_module.xml
+++ b/xml/en/docs/http/ngx_http_ssl_module.xml
@@ -187,6 +187,28 @@ a certificate will be loaded for each SSL handshake,
 and this may have a negative impact on performance.
 </para>
 
+<para>
+Since <link id="var_ssl_server_name">$ssl_server_name</link>
+is chosen by the client,
+loading certificates with such a file name should be filtered:
+<example>
+map $ssl_server_name $name {
+    hostnames;
+
+    default        www.example.org;
+
+    .example.org   www.example.org;
+    .example.com   www.example.com;
+}
+
+server {
+    listen              443 ssl;
+    ssl_certificate     certs/$name.crt;
+    ssl_certificate_key certs/$name.key;
+}
+</example>
+</para>
+
 <para id="ssl_certificate_data">
 The value
 <literal>data</literal>:<value>$variable</value>
@@ -225,7 +247,7 @@ IP addresses</link>.
 Defines a cache that stores
 <link id="ssl_certificate">SSL certificates</link> and
 <link id="ssl_certificate_key">secret keys</link>
-specified with <link id="ssl_certificate_key_variables">variables</link>.
+specified with <link id="ssl_certificate_variables">variables</link>.
 </para>
 
 <para>
@@ -273,8 +295,6 @@ disables the cache.
 <para>
 Example:
 <example>
-ssl_certificate       $ssl_server_name.crt;
-ssl_certificate_key   $ssl_server_name.key;
 ssl_certificate_cache max=1000 inactive=20s valid=1m;
 </example>
 </para>
diff --git a/xml/en/docs/stream/ngx_stream_ssl_module.xml b/xml/en/docs/stream/ngx_stream_ssl_module.xml
index 47f5d728..555a7449 100644
--- a/xml/en/docs/stream/ngx_stream_ssl_module.xml
+++ b/xml/en/docs/stream/ngx_stream_ssl_module.xml
@@ -168,6 +168,28 @@ a certificate will be loaded for each SSL handshake,
 and this may have a negative impact on performance.
 </para>
 
+<para>
+Since <link id="var_ssl_server_name">$ssl_server_name</link>
+is chosen by the client,
+loading certificates with such a file name should be filtered:
+<example>
+map $ssl_server_name $name {
+    hostnames;
+
+    default        www.example.org;
+
+    .example.org   www.example.org;
+    .example.com   www.example.com;
+}
+
+server {
+    listen              443 ssl;
+    ssl_certificate     certs/$name.crt;
+    ssl_certificate_key certs/$name.key;
+}
+</example>
+</para>
+
 <para id="ssl_certificate_data">
 The value
 <literal>data</literal>:<value>$variable</value>
@@ -207,7 +229,7 @@ IP addresses</link>.
 Defines a cache that stores
 <link id="ssl_certificate">SSL certificates</link> and
 <link id="ssl_certificate_key">secret keys</link>
-specified with <link id="ssl_certificate_key_variables">variables</link>.
+specified with <link id="ssl_certificate_variables">variables</link>.
 </para>
 
 <para>
@@ -255,8 +277,6 @@ disables the cache.
 <para>
 Example:
 <example>
-ssl_certificate       $ssl_server_name.crt;
-ssl_certificate_key   $ssl_server_name.key;
 ssl_certificate_cache max=1000 inactive=20s valid=1m;
 </example>
 </para>
diff --git a/xml/ru/docs/http/ngx_http_ssl_module.xml b/xml/ru/docs/http/ngx_http_ssl_module.xml
index 7f45f542..7a406974 100644
--- a/xml/ru/docs/http/ngx_http_ssl_module.xml
+++ b/xml/ru/docs/http/ngx_http_ssl_module.xml
@@ -189,6 +189,28 @@ ssl_certificate_key $ssl_server_name.key;
 что может отрицательно влиять на производительность.
 </para>
 
+<para>
+Поскольку значение <link id="var_ssl_server_name">$ssl_server_name</link>
+выбирается клиентом,
+загрузку сертификатов с таким именем файла следует фильтровать:
+<example>
+map $ssl_server_name $name {
+    hostnames;
+
+    default        www.example.org;
+
+    .example.org   www.example.org;
+    .example.com   www.example.com;
+}
+
+server {
+    listen              443 ssl;
+    ssl_certificate     certs/$name.crt;
+    ssl_certificate_key certs/$name.key;
+}
+</example>
+</para>
+
 <para id="ssl_certificate_data">
 Вместо <value>файла</value> можно указать значение
 <literal>data</literal>:<value>$переменная</value> (1.15.10),
@@ -227,7 +249,7 @@ IP-адресах</link>.
 Задаёт кэш, в котором могут храниться
 <link id="ssl_certificate">SSL-сертификаты</link> и
 <link id="ssl_certificate_key">секретные ключи</link>,
-полученные из <link id="ssl_certificate_key_variables">переменных</link>.
+полученные из <link id="ssl_certificate_variables">переменных</link>.
 </para>
 
 <para>
@@ -275,8 +297,6 @@ IP-адресах</link>.
 <para>
 Пример:
 <example>
-ssl_certificate       $ssl_server_name.crt;
-ssl_certificate_key   $ssl_server_name.key;
 ssl_certificate_cache max=1000 inactive=20s valid=1m;
 </example>
 </para>
diff --git a/xml/ru/docs/stream/ngx_stream_ssl_module.xml b/xml/ru/docs/stream/ngx_stream_ssl_module.xml
index 3335dc2d..2cbb6ffb 100644
--- a/xml/ru/docs/stream/ngx_stream_ssl_module.xml
+++ b/xml/ru/docs/stream/ngx_stream_ssl_module.xml
@@ -170,6 +170,28 @@ ssl_certificate_key $ssl_server_name.key;
 что может отрицательно влиять на производительность.
 </para>
 
+<para>
+Поскольку значение <link id="var_ssl_server_name">$ssl_server_name</link>
+выбирается клиентом,
+загрузку сертификатов с таким именем файла следует фильтровать:
+<example>
+map $ssl_server_name $name {
+    hostnames;
+
+    default        www.example.org;
+
+    .example.org   www.example.org;
+    .example.com   www.example.com;
+}
+
+server {
+    listen              443 ssl;
+    ssl_certificate     certs/$name.crt;
+    ssl_certificate_key certs/$name.key;
+}
+</example>
+</para>
+
 <para id="ssl_certificate_data">
 Вместо <value>файла</value> можно указать значение
 <literal>data</literal>:<value>$переменная</value> (1.15.10),
@@ -209,7 +231,7 @@ IP-адресах</link>.
 Задаёт кэш, в котором могут храниться
 <link id="ssl_certificate">SSL-сертификаты</link> и
 <link id="ssl_certificate_key">секретные ключи</link>,
-полученные из <link id="ssl_certificate_key_variables">переменных</link>.
+полученные из <link id="ssl_certificate_variables">переменных</link>.
 </para>
 
 <para>
@@ -257,8 +279,6 @@ IP-адресах</link>.
 <para>
 Пример:
 <example>
-ssl_certificate       $ssl_server_name.crt;
-ssl_certificate_key   $ssl_server_name.key;
 ssl_certificate_cache max=1000 inactive=20s valid=1m;
 </example>
 </para>