ngx_stream_ssl_module.xml

<?xml version="1.0"?>

<!--
  Copyright (C) Nginx, Inc.
  -->

<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">

<module name="Module ngx_stream_ssl_module"
        link="/en/docs/stream/ngx_stream_ssl_module.html"
        lang="en"
        rev="47">

<section id="summary">

<para>
The <literal>ngx_stream_ssl_module</literal> module (1.9.0)
provides the necessary support for a stream proxy server to work with
the SSL/TLS protocol.
</para>

<para>
This module is not built by default, it should be enabled with the
<literal>--with-stream_ssl_module</literal>
configuration parameter.
<note>
This module requires the
<link url="http://www.openssl.org">OpenSSL</link> library.
</note>
</para>

</section>


<section id="example" name="Example Configuration">

<para>
To reduce the processor load, it is recommended to
<list type="bullet">

<listitem>
set the number of
<link doc="../ngx_core_module.xml" id="worker_processes">worker processes</link>
equal to the number of processors,
</listitem>

<listitem>
enable the <link id="ssl_session_cache_shared">shared</link> session cache,
</listitem>

<listitem>
disable the <link id="ssl_session_cache_builtin">built-in</link> session cache,
</listitem>

<listitem>
and possibly increase the session <link id="ssl_session_timeout">lifetime</link>
(by default, 5 minutes):
</listitem>

</list>

<example>
<emphasis>worker_processes auto;</emphasis>

stream {

    ...

    server {
        listen              12345 ssl;

        ssl_protocols       TLSv1.2 TLSv1.3;
        ssl_ciphers         AES128-SHA:AES256-SHA:RC4-SHA:DES-CBC3-SHA:RC4-MD5;
        ssl_certificate     /usr/local/nginx/conf/cert.pem;
        ssl_certificate_key /usr/local/nginx/conf/cert.key;
        <emphasis>ssl_session_cache   shared:SSL:10m;</emphasis>
        <emphasis>ssl_session_timeout 10m;</emphasis>

        ...
    }
</example>
</para>

</section>


<section id="directives" name="Directives">

<directive name="ssl_alpn">
<syntax><value>protocol</value> ...</syntax>
<default/>
<context>stream</context>
<context>server</context>
<appeared-in>1.21.4</appeared-in>

<para>
Specifies the list of supported
<link url="https://datatracker.ietf.org/doc/html/rfc7301">ALPN</link> protocols.
One of the protocols must be
<link id="var_ssl_alpn_protocol">negotiated</link> if the client uses ALPN:
<example>
map $ssl_alpn_protocol $proxy {
    h2                127.0.0.1:8001;
    http/1.1          127.0.0.1:8002;
}

server {
    listen      12346;
    proxy_pass  $proxy;
    ssl_alpn    h2 http/1.1;
}
</example>
</para>

</directive>


<directive name="ssl_certificate">
<syntax><value>file</value></syntax>
<default/>
<context>stream</context>
<context>server</context>

<para>
Specifies a <value>file</value> with the certificate in the PEM format
for the given virtual server.
If intermediate certificates should be specified in addition to a primary
certificate, they should be specified in the same file in the following
order: the primary certificate comes first, then the intermediate certificates.
A secret key in the PEM format may be placed in the same file.
</para>

<para>
Since version 1.11.0,
this directive can be specified multiple times
to load certificates of different types, for example, RSA and ECDSA:
<example>
server {
    listen              12345 ssl;

    ssl_certificate     example.com.rsa.crt;
    ssl_certificate_key example.com.rsa.key;

    ssl_certificate     example.com.ecdsa.crt;
    ssl_certificate_key example.com.ecdsa.key;

    ...
}
</example>
<note>
Only OpenSSL 1.0.2 or higher supports separate
<link doc="../http/configuring_https_servers.xml" id="chains">certificate
chains</link>
for different certificates.
With older versions, only one certificate chain can be used.
</note>
</para>

<para id="ssl_certificate_variables">
Since version 1.15.9, variables can be used in the <value>file</value> name
when using OpenSSL 1.0.2 or higher:
<example>
ssl_certificate     $ssl_server_name.crt;
ssl_certificate_key $ssl_server_name.key;
</example>
Note that using variables implies that
a certificate will be loaded for each SSL handshake,
and this may have a negative impact on performance.
</para>

<para id="ssl_certificate_data">
The value
<literal>data</literal>:<value>$variable</value>
can be specified instead of the <value>file</value> (1.15.10),
which loads a certificate from a variable
without using intermediate files.
Note that inappropriate use of this syntax may have its security implications,
such as writing secret key data to
<link doc="../ngx_core_module.xml" id="error_log">error log</link>.
</para>

<para>
It should be kept in mind that due to the SSL/TLS protocol limitations,
for maximum interoperability with clients that do not use
<link url="http://en.wikipedia.org/wiki/Server_Name_Indication">SNI</link>,
virtual servers with different certificates should listen on
<link doc="../http/configuring_https_servers.xml"
      id="name_based_https_servers">different
IP addresses</link>.
</para>

</directive>


<directive name="ssl_certificate_cache">
<syntax><literal>off</literal></syntax>
<syntax>
    <literal>max</literal>=<value>N</value>
    [<literal>inactive</literal>=<value>time</value>]
    [<literal>valid</literal>=<value>time</value>]</syntax>
<default>off</default>
<context>stream</context>
<context>server</context>
<appeared-in>1.27.4</appeared-in>

<para>
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>.
</para>

<para>
The directive has the following parameters:
<list type="tag">

<tag-name id="ssl_certificate_cache_max">
<literal>max</literal>
</tag-name>
<tag-desc>
sets the maximum number of elements in the cache;
on cache overflow the least recently used (LRU) elements are removed;
</tag-desc>

<tag-name id="ssl_certificate_cache_inactive">
<literal>inactive</literal>
</tag-name>
<tag-desc>
defines a time after which an element is removed from the cache
if it has not been accessed during this time;
by default, it is 10 seconds;
</tag-desc>

<tag-name id="ssl_certificate_cache_valid">
<literal>valid</literal>
</tag-name>
<tag-desc>
defines a time during which
an element in the cache is considered valid
and can be reused;
by default, it is 60 seconds.
Certificates that exceed this time will be reloaded or revalidated;
</tag-desc>

<tag-name id="ssl_certificate_cache_off">
<literal>off</literal>
</tag-name>
<tag-desc>
disables the cache.
</tag-desc>

</list>
</para>

<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>

</directive>


<directive name="ssl_certificate_compression">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>stream</context>
<context>server</context>
<appeared-in>1.29.1</appeared-in>

<para>
Enables TLS 1.3
<link url="https://datatracker.ietf.org/doc/html/rfc8879">compression</link>
of server certificates.
<note>
The directive is supported when using OpenSSL 3.2 or higher;
the list of supported compression algorithms is provided by the library.
</note>
<note>
The directive is supported when using BoringSSL;
the list of supported compression algorithms includes
<literal>zlib</literal> (1.29.3).
</note>
</para>

</directive>


<directive name="ssl_certificate_key">
<syntax><value>file</value></syntax>
<default/>
<context>stream</context>
<context>server</context>

<para>
Specifies a <value>file</value> with the secret key in the PEM format
for the given virtual server.
</para>

<para>
The value
<literal>engine</literal>:<value>name</value>:<value>id</value>
can be specified instead of the <value>file</value>,
which loads a secret key with a specified <value>id</value>
from the OpenSSL engine <value>name</value>.
</para>

<para>
The value
<literal>store</literal>:<value>scheme</value>:<value>id</value>
can be specified instead of the <value>file</value> (1.29.0),
which is used to load a secret key with a specified <value>id</value>
and OpenSSL provider registered URI <value>scheme</value>, such as
<link url="https://datatracker.ietf.org/doc/html/rfc7512"><literal>pkcs11</literal></link>.
</para>

<para id="ssl_certificate_key_data">
The value
<literal>data</literal>:<value>$variable</value>
can be specified instead of the <value>file</value> (1.15.10),
which loads a secret key from a variable without using intermediate files.
Note that inappropriate use of this syntax may have its security implications,
such as writing secret key data to
<link doc="../ngx_core_module.xml" id="error_log">error log</link>.
</para>

<para id="ssl_certificate_key_variables">
Since version 1.15.9, variables can be used in the <value>file</value> name
when using OpenSSL 1.0.2 or higher.
</para>

</directive>


<directive name="ssl_ciphers">
<syntax><value>ciphers</value></syntax>
<default>HIGH:!aNULL:!MD5</default>
<context>stream</context>
<context>server</context>

<para>
Specifies the enabled ciphers.
The ciphers are specified in the format understood by the
OpenSSL library, for example:
<example>
ssl_ciphers ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;
</example>
</para>

<para>
The full list can be viewed using the
“<command>openssl ciphers</command>” command.
</para>

</directive>


<directive name="ssl_client_certificate">
<syntax><value>file</value></syntax>
<default/>
<context>stream</context>
<context>server</context>
<appeared-in>1.11.8</appeared-in>

<para>
Specifies a <value>file</value> with trusted CA certificates in the PEM format
used to <link id="ssl_verify_client">verify</link> client certificates and
OCSP responses if <link id="ssl_stapling"/> is enabled.
</para>

<para>
The list of certificates will be sent to clients.
If this is not desired, the <link id="ssl_trusted_certificate"/>
directive can be used.
</para>

</directive>


<directive name="ssl_conf_command">
<syntax><value>name</value> <value>value</value></syntax>
<default/>
<context>stream</context>
<context>server</context>
<appeared-in>1.19.4</appeared-in>

<para>
Sets arbitrary OpenSSL configuration
<link url="https://www.openssl.org/docs/man1.1.1/man3/SSL_CONF_cmd.html">commands</link>.
<note>
The directive is supported when using OpenSSL 1.0.2 or higher.
</note>
</para>

<para>
Several <literal>ssl_conf_command</literal> directives
can be specified on the same level:
<example>
ssl_conf_command Options PrioritizeChaCha;
ssl_conf_command Ciphersuites TLS_CHACHA20_POLY1305_SHA256;
</example>
These directives are inherited from the previous configuration level
if and only if there are no <literal>ssl_conf_command</literal> directives
defined on the current level.
</para>

<para>
<note>
Note that configuring OpenSSL directly
might result in unexpected behavior.
</note>
</para>

</directive>


<directive name="ssl_crl">
<syntax><value>file</value></syntax>
<default/>
<context>stream</context>
<context>server</context>
<appeared-in>1.11.8</appeared-in>

<para>
Specifies a <value>file</value> with revoked certificates (CRL)
in the PEM format used to <link id="ssl_verify_client">verify</link>
client certificates.
When using intermediate certificates, their CRLs should be
specified in the same file.
</para>

</directive>


<directive name="ssl_dhparam">
<syntax><value>file</value></syntax>
<default/>
<context>stream</context>
<context>server</context>

<para>
Specifies a <value>file</value> with DH parameters for DHE ciphers.
</para>

<para>
By default no parameters are set,
and therefore DHE ciphers will not be used.
<note>
Prior to version 1.11.0, builtin parameters were used by default.
</note>
</para>

</directive>


<directive name="ssl_ecdh_curve">
<syntax><value>curve</value></syntax>
<default>auto</default>
<context>stream</context>
<context>server</context>

<para>
Specifies a <value>curve</value> for ECDHE ciphers.
</para>

<para>
When using OpenSSL 1.0.2 or higher,
it is possible to specify multiple curves (1.11.0), for example:
<example>
ssl_ecdh_curve prime256v1:secp384r1;
</example>
</para>

<para>
The special value <literal>auto</literal> (1.11.0) instructs nginx to use
a list built into the OpenSSL library when using OpenSSL 1.0.2 or higher,
or <literal>prime256v1</literal> with older versions.
</para>

<para>
<note>
Prior to version 1.11.0,
the <literal>prime256v1</literal> curve was used by default.
</note>
</para>

<para>
<note>
When using OpenSSL 1.0.2 or higher,
this directive sets the list of curves supported by the server.
Thus, in order for ECDSA certificates to work,
it is important to include the curves used in the certificates.
</note>
</para>

</directive>


<directive name="ssl_ech_file">
<syntax><value>file</value></syntax>
<default/>
<context>stream</context>
<context>server</context>
<appeared-in>1.29.4</appeared-in>

<para>
Specifies a <value>file</value> with encrypted ClientHello configuration
(<literal>ECHConfig</literal>) in the
<link url="https://datatracker.ietf.org/doc/draft-farrell-tls-pemesni/">PEM</link>
format used to enable TLS 1.3
<link url="https://datatracker.ietf.org/doc/html/draft-ietf-tls-esni">ECH</link>
in shared mode.
</para>

<para>
<note>
The directive is currently supported only when using OpenSSL
<link url="https://github.com/openssl/openssl/tree/feature/ech">ECH
feature branch</link>.
</note>
</para>

</directive>


<directive name="ssl_handshake_timeout">
<syntax><value>time</value></syntax>
<default>60s</default>
<context>stream</context>
<context>server</context>

<para>
Specifies a timeout for the SSL handshake to complete.
</para>

</directive>


<directive name="ssl_key_log">
<syntax>path</syntax>
<default/>
<context>stream</context>
<context>server</context>
<appeared-in>1.27.2</appeared-in>

<para>
Enables logging of client connection SSL keys
and specifies the path to the key log file.
Keys are logged in the
<link url="https://datatracker.ietf.org/doc/html/draft-ietf-tls-keylogfile">SSLKEYLOGFILE</link>
format compatible with Wireshark.
</para>

<para>
<note>
This directive is available as part of our
<commercial_version>commercial subscription</commercial_version>.
</note>
</para>

</directive>


<directive name="ssl_ocsp">
<syntax><literal>on</literal> |
        <literal>off</literal> |
        <literal>leaf</literal></syntax>
<default>off</default>
<context>stream</context>
<context>server</context>
<appeared-in>1.27.2</appeared-in>

<para>
Enables OCSP validation of the client certificate chain.
The <literal>leaf</literal> parameter
enables validation of the client certificate only.
</para>

<para>
For the OCSP validation to work,
the <link id="ssl_verify_client"/> directive should be set to
<literal>on</literal> or <literal>optional</literal>.
</para>

<para>
To resolve the OCSP responder hostname,
the <link doc="ngx_stream_core_module.xml" id="resolver"/> directive
should also be specified.
</para>

<para>
Example:
<example>
ssl_verify_client on;
ssl_ocsp          on;
resolver          192.0.2.1;
</example>
</para>

</directive>


<directive name="ssl_ocsp_cache">
<syntax>
    <literal>off</literal> |
    [<literal>shared</literal>:<value>name</value>:<value>size</value>]</syntax>
<default>off</default>
<context>stream</context>
<context>server</context>
<appeared-in>1.27.2</appeared-in>

<para>
Sets <literal>name</literal> and <literal>size</literal> of the cache
that stores client certificates status for OCSP validation.
The cache is shared between all worker processes.
A cache with the same name can be used in several
virtual servers.
</para>

<para>
The <literal>off</literal> parameter prohibits the use of the cache.
</para>

</directive>


<directive name="ssl_ocsp_responder">
<syntax><value>url</value></syntax>
<default/>
<context>stream</context>
<context>server</context>
<appeared-in>1.27.2</appeared-in>

<para>
Overrides the URL of the OCSP responder specified in the
“<link url="https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.2.1">Authority
Information Access</link>” certificate extension
for <link id="ssl_ocsp">validation</link> of client certificates.
</para>

<para>
Only “<literal>http://</literal>” OCSP responders are supported:
<example>
ssl_ocsp_responder http://ocsp.example.com/;
</example>
</para>

</directive>


<directive name="ssl_password_file">
<syntax><value>file</value></syntax>
<default/>
<context>stream</context>
<context>server</context>

<para>
Specifies a <value>file</value> with passphrases for
<link id="ssl_certificate_key">secret keys</link>
where each passphrase is specified on a separate line.
Passphrases are tried in turn when loading the key.
</para>

<para>
Example:
<example>
stream {
    ssl_password_file /etc/keys/global.pass;
    ...

    server {
        listen 127.0.0.1:12345;
        ssl_certificate_key /etc/keys/first.key;
    }

    server {
        listen 127.0.0.1:12346;

        # named pipe can also be used instead of a file
        ssl_password_file /etc/keys/fifo;
        ssl_certificate_key /etc/keys/second.key;
    }
}
</example>
</para>

</directive>


<directive name="ssl_prefer_server_ciphers">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>stream</context>
<context>server</context>

<para>
Specifies that server ciphers should be preferred over client ciphers
when the SSLv3 and TLS protocols are used.
</para>

</directive>


<directive name="ssl_protocols">
<syntax>
    [<literal>SSLv2</literal>]
    [<literal>SSLv3</literal>]
    [<literal>TLSv1</literal>]
    [<literal>TLSv1.1</literal>]
    [<literal>TLSv1.2</literal>]
    [<literal>TLSv1.3</literal>]</syntax>
<default>TLSv1.2 TLSv1.3</default>
<context>stream</context>
<context>server</context>

<para>
Enables the specified protocols.
</para>

<para>
If the directive is specified
on the <link doc="ngx_stream_core_module.xml" id="server"/> level,
the value from the default server can be used.
Details are provided in the
“<link doc="../http/server_names.xml" id="virtual_server_selection">Virtual
server selection</link>” section.
</para>

<para>
<note>
The <literal>TLSv1.1</literal> and <literal>TLSv1.2</literal> parameters
work only when OpenSSL 1.0.1 or higher is used.
</note>
<note>
The <literal>TLSv1.3</literal> parameter (1.13.0) works only when
OpenSSL 1.1.1 or higher is used.
</note>
<note>
The <literal>TLSv1.3</literal> parameter is used by default
since 1.23.4.
</note>
</para>

</directive>


<directive name="ssl_reject_handshake">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>stream</context>
<context>server</context>
<appeared-in>1.25.5</appeared-in>

<para>
If enabled, SSL handshakes in
the <link doc="ngx_stream_core_module.xml" id="server"/> block will be rejected.
</para>

<para>
For example, in the following configuration, SSL handshakes with
server names other than <literal>example.com</literal> are rejected:
<example>
server {
    listen               443 ssl default_server;
    ssl_reject_handshake on;
}

server {
    listen              443 ssl;
    server_name         example.com;
    ssl_certificate     example.com.crt;
    ssl_certificate_key example.com.key;
}
</example>
</para>

</directive>


<directive name="ssl_session_cache">
<syntax>
    <literal>off</literal> |
    <literal>none</literal> |
    [<literal>builtin</literal>[:<value>size</value>]]
    [<literal>shared</literal>:<value>name</value>:<value>size</value>]</syntax>
<default>none</default>
<context>stream</context>
<context>server</context>

<para>
Sets the types and sizes of caches that store session parameters.
A cache can be of any of the following types:
<list type="tag">

<tag-name><literal>off</literal></tag-name>
<tag-desc>
the use of a session cache is strictly prohibited:
nginx explicitly tells a client that sessions may not be reused.
</tag-desc>

<tag-name><literal>none</literal></tag-name>
<tag-desc>
the use of a session cache is gently disallowed:
nginx tells a client that sessions may be reused, but does not
actually store session parameters in the cache.
</tag-desc>

<tag-name id="ssl_session_cache_builtin"><literal>builtin</literal></tag-name>
<tag-desc>
a cache built in OpenSSL; used by one worker process only.
The cache size is specified in sessions.
If size is not given, it is equal to 20480 sessions.
Use of the built-in cache can cause memory fragmentation.
</tag-desc>

<tag-name id="ssl_session_cache_shared"><literal>shared</literal></tag-name>
<tag-desc>
a cache shared between all worker processes.
The cache size is specified in bytes; one megabyte can store
about 4000 sessions.
Each shared cache should have an arbitrary name.
A cache with the same name can be used in several
virtual servers.
It is also used to automatically generate, store, and
periodically rotate TLS session ticket keys (1.23.2)
unless configured explicitly
using the <link id="ssl_session_ticket_key"/> directive.
</tag-desc>

</list>
</para>

<para>
Both cache types can be used simultaneously, for example:
<example>
ssl_session_cache builtin:1000 shared:SSL:10m;
</example>
but using only shared cache without the built-in cache should
be more efficient.
</para>

</directive>


<directive name="ssl_session_ticket_key">
<syntax><value>file</value></syntax>
<default/>
<context>stream</context>
<context>server</context>

<para>
Sets a <value>file</value> with the secret key used to encrypt
and decrypt TLS session tickets.
The directive is necessary if the same key has to be shared between
multiple servers.
By default, a randomly generated key is used.
</para>

<para>
If several keys are specified, only the first key is
used to encrypt TLS session tickets.
This allows configuring key rotation, for example:
<example>
ssl_session_ticket_key current.key;
ssl_session_ticket_key previous.key;
</example>
</para>

<para>
The <value>file</value> must contain 80 or 48 bytes
of random data and can be created using the following command:
<example>
openssl rand 80 > ticket.key
</example>
Depending on the file size either AES256 (for 80-byte keys, 1.11.8)
or AES128 (for 48-byte keys) is used for encryption.
</para>

</directive>


<directive name="ssl_session_tickets">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>on</default>
<context>stream</context>
<context>server</context>

<para>
Enables or disables session resumption through
<link url="https://datatracker.ietf.org/doc/html/rfc5077">TLS session tickets</link>.
</para>

</directive>


<directive name="ssl_session_timeout">
<syntax><value>time</value></syntax>
<default>5m</default>
<context>stream</context>
<context>server</context>

<para>
Specifies a time during which a client may reuse the
session parameters.
</para>

</directive>


<directive name="ssl_stapling">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>stream</context>
<context>server</context>
<appeared-in>1.27.2</appeared-in>

<para>
Enables or disables
<link url="https://datatracker.ietf.org/doc/html/rfc6066#section-8">stapling
of OCSP responses</link> by the server.
Example:
<example>
ssl_stapling on;
resolver 192.0.2.1;
</example>
</para>

<para>
For the OCSP stapling to work, the certificate of the server certificate
issuer should be known.
If the <link id="ssl_certificate"/> file does
not contain intermediate certificates,
the certificate of the server certificate issuer should be
present in the
<link id="ssl_trusted_certificate"/> file.
</para>

<para>
For a resolution of the OCSP responder hostname,
the <link doc="ngx_stream_core_module.xml" id="resolver"/> directive
should also be specified.
</para>

</directive>


<directive name="ssl_stapling_file">
<syntax><value>file</value></syntax>
<default/>
<context>stream</context>
<context>server</context>
<appeared-in>1.27.2</appeared-in>

<para>
When set, the stapled OCSP response will be taken from the
specified <value>file</value> instead of querying
the OCSP responder specified in the server certificate.
</para>

<para>
The file should be in the DER format as produced by the
“<literal>openssl ocsp</literal>” command.
</para>

</directive>


<directive name="ssl_stapling_responder">
<syntax><value>url</value></syntax>
<default/>
<context>stream</context>
<context>server</context>
<appeared-in>1.27.2</appeared-in>

<para>
Overrides the URL of the OCSP responder specified in the
“<link url="https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.2.1">Authority
Information Access</link>” certificate extension.
</para>

<para>
Only “<literal>http://</literal>” OCSP responders are supported:
<example>
ssl_stapling_responder http://ocsp.example.com/;
</example>
</para>

</directive>


<directive name="ssl_stapling_verify">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>stream</context>
<context>server</context>
<appeared-in>1.27.2</appeared-in>

<para>
Enables or disables verification of OCSP responses by the server.
</para>

<para>
For verification to work, the certificate of the server certificate
issuer, the root certificate, and all intermediate certificates
should be configured as trusted using the
<link id="ssl_trusted_certificate"/> directive.
</para>

</directive>


<directive name="ssl_trusted_certificate">
<syntax><value>file</value></syntax>
<default/>
<context>stream</context>
<context>server</context>
<appeared-in>1.11.8</appeared-in>

<para>
Specifies a <value>file</value> with trusted CA certificates in the PEM format
used to <link id="ssl_verify_client">verify</link> client certificates and
OCSP responses if <link id="ssl_stapling"/> is enabled.
</para>

<para>
In contrast to the certificate set by <link id="ssl_client_certificate"/>,
the list of these certificates will not be sent to clients.
</para>

</directive>


<directive name="ssl_verify_client">
<syntax>
    <literal>on</literal> | <literal>off</literal> |
    <literal>optional</literal> | <literal>optional_no_ca</literal></syntax>
<default>off</default>
<context>stream</context>
<context>server</context>
<appeared-in>1.11.8</appeared-in>

<para>
Enables verification of client certificates.
The verification result is stored in the
<link id="var_ssl_client_verify">$ssl_client_verify</link> variable.
If an error has occurred during the client certificate verification
or a client has not presented the required certificate,
the connection is closed.
</para>

<para>
The <literal>optional</literal> parameter requests the client
certificate and verifies it if the certificate is present.
</para>

<para>
The <literal>optional_no_ca</literal> parameter
requests the client
certificate but does not require it to be signed by a trusted CA certificate.
This is intended for the use in cases when a service that is external to nginx
performs the actual certificate verification.
The contents of the certificate is accessible through the
<link id="var_ssl_client_cert">$ssl_client_cert</link> variable.
</para>

</directive>


<directive name="ssl_verify_depth">
<syntax><value>number</value></syntax>
<default>1</default>
<context>stream</context>
<context>server</context>
<appeared-in>1.11.8</appeared-in>

<para>
Sets the verification depth in the client certificates chain.
</para>

</directive>

</section>


<section id="variables" name="Embedded Variables">

<para>
The <literal>ngx_stream_ssl_module</literal> module supports variables
since 1.11.2.
<list type="tag">

<tag-name id="var_ssl_alpn_protocol"><var>$ssl_alpn_protocol</var></tag-name>
<tag-desc>
returns the protocol selected by ALPN during the SSL handshake,
or an empty string otherwise (1.21.4);
</tag-desc>

<tag-name id="var_ssl_cipher"><var>$ssl_cipher</var></tag-name>
<tag-desc>
returns the name of the cipher used
for an established SSL connection;
</tag-desc>

<tag-name id="var_ssl_ciphers"><var>$ssl_ciphers</var></tag-name>
<tag-desc>
returns the list of ciphers supported by the client (1.11.7).
Known ciphers are listed by names, unknown are shown in hexadecimal,
for example:
<example>
AES128-SHA:AES256-SHA:0x00ff
</example>
<note>
The variable is fully supported only when using OpenSSL version 1.0.2 or higher.
With older versions, the variable is available
only for new sessions and lists only known ciphers.
</note>
</tag-desc>

<tag-name id="var_ssl_client_cert"><var>$ssl_client_cert</var></tag-name>
<tag-desc>
returns the client certificate in the PEM format
for an established SSL connection, with each line except the first
prepended with the tab character (1.11.8);
</tag-desc>

<tag-name id="var_ssl_client_fingerprint"><var>$ssl_client_fingerprint</var></tag-name>
<tag-desc>
returns the SHA1 fingerprint of the client certificate
for an established SSL connection (1.11.8);
</tag-desc>

<tag-name id="var_ssl_client_i_dn"><var>$ssl_client_i_dn</var></tag-name>
<tag-desc>
returns the “issuer DN” string of the client certificate
for an established SSL connection according to
<link url="https://datatracker.ietf.org/doc/html/rfc2253">RFC 2253</link> (1.11.8);
</tag-desc>

<tag-name id="var_ssl_client_raw_cert"><var>$ssl_client_raw_cert</var>
</tag-name>
<tag-desc>
returns the client certificate in the PEM format
for an established SSL connection (1.11.8);
</tag-desc>

<tag-name id="var_ssl_client_s_dn"><var>$ssl_client_s_dn</var></tag-name>
<tag-desc>
returns the “subject DN” string of the client certificate
for an established SSL connection according to
<link url="https://datatracker.ietf.org/doc/html/rfc2253">RFC 2253</link> (1.11.8);
</tag-desc>

<tag-name id="var_ssl_client_serial"><var>$ssl_client_serial</var></tag-name>
<tag-desc>
returns the serial number of the client certificate
for an established SSL connection (1.11.8);
</tag-desc>

<tag-name id="var_ssl_client_sigalg"><var>$ssl_client_sigalg</var></tag-name>
<tag-desc>
returns the
<link url="https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-16">signature algorithm</link>
for the client certificate for an established SSL connection (1.29.3).
<note>
The variable is supported only when using OpenSSL version 3.5 or higher.
With older versions, the variable value will be an empty string.
</note>
<note>
The variable is available only for new sessions.
</note>
</tag-desc>

<tag-name id="var_ssl_client_v_end"><var>$ssl_client_v_end</var></tag-name>
<tag-desc>
returns the end date of the client certificate (1.11.8);
</tag-desc>

<tag-name id="var_ssl_client_v_remain"><var>$ssl_client_v_remain</var></tag-name>
<tag-desc>
returns the number of days
until the client certificate expires (1.11.8);
</tag-desc>

<tag-name id="var_ssl_client_v_start"><var>$ssl_client_v_start</var></tag-name>
<tag-desc>
returns the start date of the client certificate (1.11.8);
</tag-desc>

<tag-name id="var_ssl_client_verify"><var>$ssl_client_verify</var></tag-name>
<tag-desc>
returns the result of client certificate verification (1.11.8):
“<literal>SUCCESS</literal>”, “<literal>FAILED:</literal><value>reason</value>”,
and “<literal>NONE</literal>” if a certificate was not present;
</tag-desc>

<tag-name id="var_ssl_curve"><var>$ssl_curve</var></tag-name>
<tag-desc>
returns the negotiated curve used for
SSL handshake key exchange process (1.21.5).
Known curves are listed by names, unknown are shown in hexadecimal,
for example:
<example>
prime256v1
</example>
<note>
The variable is supported only when using OpenSSL version 3.0 or higher.
With older versions, the variable value will be an empty string.
</note>
</tag-desc>

<tag-name id="var_ssl_curves"><var>$ssl_curves</var></tag-name>
<tag-desc>
returns the list of curves supported by the client (1.11.7).
Known curves are listed by names, unknown are shown in hexadecimal,
for example:
<example>
0x001d:prime256v1:secp521r1:secp384r1
</example>
<note>
The variable is supported only when using OpenSSL version 1.0.2 or higher.
With older versions, the variable value will be an empty string.
</note>
<note>
The variable is available only for new sessions.
</note>
</tag-desc>

<tag-name id="var_ssl_ech_outer_server_name"><var>$ssl_ech_outer_server_name</var></tag-name>
<tag-desc>
returns the public server name requested through
<link url="http://en.wikipedia.org/wiki/Server_Name_Indication">SNI</link>
if TLS 1.3 <link id="ssl_ech_file">ECH</link> was accepted,
otherwise “” (1.29.4);
</tag-desc>

<tag-name id="var_ssl_ech_status"><var>$ssl_ech_status</var></tag-name>
<tag-desc>
returns the result of TLS 1.3 <link id="ssl_ech_file">ECH</link> processing:
“<literal>FAILED</literal>”,
“<literal>BACKEND</literal>”,
“<literal>GREASE</literal>”,
“<literal>SUCCESS</literal>”, or
“<literal>NOT_TRIED</literal>” (1.29.4);
<note>
The variable is currently supported only when using OpenSSL
<link url="https://github.com/openssl/openssl/tree/feature/ech">ECH feature branch</link>
and is therefore subject to change.
The variable value will otherwise be an empty string.
</note>
</tag-desc>

<tag-name id="var_ssl_protocol"><var>$ssl_protocol</var></tag-name>
<tag-desc>
returns the protocol of an established SSL connection;
</tag-desc>

<tag-name id="var_ssl_server_name"><var>$ssl_server_name</var></tag-name>
<tag-desc>
returns the server name requested through
<link url="http://en.wikipedia.org/wiki/Server_Name_Indication">SNI</link>;
</tag-desc>

<tag-name id="var_ssl_session_id"><var>$ssl_session_id</var></tag-name>
<tag-desc>
returns the session identifier of an established SSL connection;
</tag-desc>

<tag-name id="var_ssl_session_reused"><var>$ssl_session_reused</var></tag-name>
<tag-desc>
returns “<literal>r</literal>” if an SSL session was reused,
or “<literal>.</literal>” otherwise.
</tag-desc>

<tag-name id="var_ssl_sigalg"><var>$ssl_sigalg</var></tag-name>
<tag-desc>
returns the
<link url="https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-16">signature algorithm</link>
for the server certificate for an established SSL connection (1.29.3).
<note>
The variable is supported only when using OpenSSL version 3.5 or higher.
With older versions, the variable value will be an empty string.
</note>
<note>
The variable is available only for new sessions.
</note>
</tag-desc>

</list>
</para>

</section>

</module>