Skip to content

Documented restricting $ssl_server_name in certificate file names - #304

Draft
VadimZhestikov wants to merge 1 commit into
nginx:mainfrom
VadimZhestikov:docs-ssl-certificate-variable-warning
Draft

Documented restricting $ssl_server_name in certificate file names#304
VadimZhestikov wants to merge 1 commit into
nginx:mainfrom
VadimZhestikov:docs-ssl-certificate-variable-warning

Conversation

@VadimZhestikov

Copy link
Copy Markdown
Contributor

Problem

The documentation for ssl_certificate presents $ssl_server_name used directly
in the certificate file name as a straightforward SNI-based selection pattern,
with only a performance caveat. $ssl_server_name holds the server name
requested by the client and is not validated, so using it directly in the file
name lets a client influence which file is loaded -- for example, by sending an
SNI value containing a path separator or ../.

The behavior is by design (the variable intentionally reflects the raw SNI; see
fd97b2a80), so this is a documentation gap rather than a code defect, but the
example currently leads administrators toward an unsafe configuration.

Solution

Added a note to the ssl_certificate variables section explaining that
$ssl_server_name is client-controlled and not validated, and recommending that
the value be restricted to an expected set of names, for example with a map
allowlist. English and Russian.

Testing

xmllint --noout --valid against dtd/ passes for both files.

Comment thread xml/en/docs/http/ngx_http_ssl_module.xml Outdated
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.
@VadimZhestikov
VadimZhestikov force-pushed the docs-ssl-certificate-variable-warning branch from 404886c to 4fefaa5 Compare August 7, 2026 14:25
@VadimZhestikov

Copy link
Copy Markdown
Contributor Author

Thanks, reworked as suggested: dropped the repeated $ssl_server_name description and replaced it with a terse note --

Since $ssl_server_name is chosen by the client, loading certificates with such a file name should be filtered, for example, with the map directive:

-- followed by the map example. Russian translation updated to match.

@VadimZhestikov
VadimZhestikov requested a review from pluknet August 7, 2026 14:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants