ngx_http_ssl_module.xml

<?xml version="1.0"?>

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

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

<module name="Модуль ngx_http_ssl_module"
        link="/ru/docs/http/ngx_http_ssl_module.html"
        lang="ru"
        rev="74">

<section id="summary">

<para>
Модуль <literal>ngx_http_ssl_module</literal> обеспечивает работу
по протоколу HTTPS.
</para>

<para>
По умолчанию этот модуль не собирается, его сборку необходимо
разрешить с помощью конфигурационного параметра
<literal>--with-http_ssl_module</literal>.
<note>
Для сборки и работы этого модуля нужна библиотека
<link url="http://www.openssl.org">OpenSSL</link>.
</note>
</para>

</section>


<section id="example" name="Пример конфигурации">

<para>
Для уменьшения загрузки процессора рекомендуется
<list type="bullet">

<listitem>
установить число
<link doc="../ngx_core_module.xml" id="worker_processes">рабочих процессов</link>
равным числу процессоров,
</listitem>

<listitem>
разрешить
<link doc="ngx_http_core_module.xml" id="keepalive_timeout">keep-alive</link>
соединения,
</listitem>

<listitem>
включить <link id="ssl_session_cache_shared">разделяемый</link> кэш сессий,
</listitem>

<listitem>
выключить <link id="ssl_session_cache_builtin">встроенный</link> кэш сессий
</listitem>

<listitem>
и, возможно, увеличить <link id="ssl_session_timeout">время жизни</link> сессии
(по умолчанию 5 минут):
</listitem>

</list>

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

http {

    ...

    server {
        listen              443 ssl;
        <emphasis>keepalive_timeout   70;</emphasis>

        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="Директивы">

<directive name="ssl">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>

<para>
Эта директива устарела в версии 1.15.0
и была удалена в версии 1.25.1.
Вместо неё следует
использовать параметр <literal>ssl</literal>
директивы <link doc="ngx_http_core_module.xml" id="listen"/>.
</para>

</directive>


<directive name="ssl_buffer_size">
<syntax><value>size</value></syntax>
<default>16k</default>
<context>http</context>
<context>server</context>
<appeared-in>1.5.9</appeared-in>

<para>
Задаёт размер буфера, используемого при отправке данных.
</para>

<para>
По умолчанию размер буфера равен 16k, что соответствует минимальным
накладным расходам при передаче больших ответов.
С целью минимизации времени получения начала ответа (Time To First Byte)
может быть полезно использовать меньшие значения,
например:
<example>
ssl_buffer_size 4k;
</example>
</para>

</directive>


<directive name="ssl_certificate">
<syntax><value>файл</value></syntax>
<default/>
<context>http</context>
<context>server</context>

<para>
Указывает <value>файл</value> с сертификатом в формате PEM
для данного виртуального сервера.
Если вместе с основным сертификатом нужно указать промежуточные,
то они должны находиться в этом же файле в следующем порядке: сначала
основной сертификат, а затем промежуточные.
В этом же файле может находиться секретный ключ в формате PEM.
</para>

<para>
Начиная с версии 1.11.0
эта директива может быть указана несколько раз
для загрузки сертификатов разных типов, например RSA и ECDSA:
<example>
server {
    listen              443 ssl;
    server_name         example.com;

    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>
Возможность задавать отдельные
<link doc="configuring_https_servers.xml" id="chains">цепочки
сертификатов</link>
для разных сертификатов есть только в OpenSSL 1.0.2 и выше.
Для более старых версий следует указывать только одну цепочку сертификатов.
</note>
</para>

<para id="ssl_certificate_variables">
Начиная с версии 1.15.9 в имени файла можно использовать переменные
при использовании OpenSSL 1.0.2 и выше:
<example>
ssl_certificate     $ssl_server_name.crt;
ssl_certificate_key $ssl_server_name.key;
</example>
Однако нужно учитывать, что при использовании переменных
сертификат загружается при каждой операции SSL handshake,
что может отрицательно влиять на производительность.
</para>

<para id="ssl_certificate_data">
Вместо <value>файла</value> можно указать значение
<literal>data</literal>:<value>$переменная</value> (1.15.10),
при котором сертификат загружается из переменной
без использования промежуточных файлов.
При этом следует учитывать, что ненадлежащее использование
подобного синтаксиса может быть небезопасно,
например данные секретного ключа могут попасть в
<link doc="../ngx_core_module.xml" id="error_log">лог ошибок</link>.
</para>

<para>
Нужно иметь в виду, что из-за ограничения протокола SSL/TLS
для максимальной совместимости с клиентами, которые не используют
<link url="http://en.wikipedia.org/wiki/Server_Name_Indication">SNI</link>,
виртуальные серверы с разными сертификатами должны слушать на
<link doc="configuring_https_servers.xml" id="name_based_https_servers">разных
IP-адресах</link>.
</para>

</directive>


<directive name="ssl_certificate_cache">
<syntax><literal>off</literal></syntax>
<syntax>
    <literal>max</literal>=<value>N</value>
    [<literal>inactive</literal>=<value>время</value>]
    [<literal>valid</literal>=<value>время</value>]</syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<appeared-in>1.27.4</appeared-in>

<para>
Задаёт кэш, в котором могут храниться
<link id="ssl_certificate">SSL-сертификаты</link> и
<link id="ssl_certificate_key">секретные ключи</link>,
полученные из <link id="ssl_certificate_key_variables">переменных</link>.
</para>

<para>
У директивы есть следующие параметры:
<list type="tag">

<tag-name id="ssl_certificate_cache_max">
<literal>max</literal>
</tag-name>
<tag-desc>
задаёт максимальное число элементов в кэше;
при переполнении кэша удаляются наименее востребованные элементы (LRU);
</tag-desc>

<tag-name id="ssl_certificate_cache_inactive">
<literal>inactive</literal>
</tag-name>
<tag-desc>
задаёт время, после которого элемент кэша удаляется,
если к нему не было обращений в течение этого времени;
по умолчанию 10 секунд;
</tag-desc>

<tag-name id="ssl_certificate_cache_valid">
<literal>valid</literal>
</tag-name>
<tag-desc>
задает время, в течение которого
элемент кэша считается действительным
и может быть повторно использован,
по умолчанию 60 секунд.
По завершении этого времени сертификат будет обновлён или повторно проверен;
</tag-desc>

<tag-name id="ssl_certificate_cache_off">
<literal>off</literal>
</tag-name>
<tag-desc>
запрещает кэш.
</tag-desc>

</list>
</para>

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

</directive>


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

<para>
Разрешает
<link url="https://datatracker.ietf.org/doc/html/rfc8879">сжатие</link>
серверных сертификатов при использовании TLS 1.3.
<note>
Директива поддерживается при использовании OpenSSL 3.2 и выше;
список поддерживаемых алгоритмов сжатия обеспечивается библиотекой.
</note>
<note>
Директива поддерживается при использовании BoringSSL;
список поддерживаемых алгоритмов сжатия включает
<literal>zlib</literal> (1.29.3).
</note>
</para>

</directive>


<directive name="ssl_certificate_key">
<syntax><value>файл</value></syntax>
<default/>
<context>http</context>
<context>server</context>

<para>
Указывает <value>файл</value> с секретным ключом в формате PEM
для данного виртуального сервера.
</para>

<para>
Вместо <value>файла</value> можно указать значение
<literal>engine</literal>:<value>имя</value>:<value>id</value> (1.7.9),
которое загружает ключ с указанным <value>id</value>
из OpenSSL engine с заданным <value>именем</value>.
</para>

<para>
Вместо <value>файла</value> можно указать значение
<literal>store</literal>:<value>схема</value>:<value>id</value> (1.29.0),
которое используется для загрузки ключа с указанным <value>id</value>
и зарегистрированной провайдером OpenSSL <value>схемой</value> URI, такой как
<link url="https://datatracker.ietf.org/doc/html/rfc7512"><literal>pkcs11</literal></link>.
</para>

<para id="ssl_certificate_key_data">
Вместо <value>файла</value> можно указать значение
<literal>data</literal>:<value>$переменная</value> (1.15.10),
при котором секретный ключ загружается из переменной
без использования промежуточных файлов.
При этом следует учитывать, что ненадлежащее использование
подобного синтаксиса может быть небезопасно,
например данные секретного ключа могут попасть в
<link doc="../ngx_core_module.xml" id="error_log">лог ошибок</link>.
</para>

<para id="ssl_certificate_key_variables">
Начиная с версии 1.15.9 в имени файла можно использовать переменные
при использовании OpenSSL 1.0.2 и выше.
</para>

</directive>


<directive name="ssl_ciphers">
<syntax><value>шифры</value></syntax>
<default>HIGH:!aNULL:!MD5</default>
<context>http</context>
<context>server</context>

<para>
Описывает разрешённые шифры.
Шифры задаются в формате, поддерживаемом библиотекой
OpenSSL, например:
<example>
ssl_ciphers ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;
</example>
</para>

<para>
Полный список можно посмотреть с помощью команды
“<command>openssl ciphers</command>”.
</para>

<para>
<note>
В предыдущих версиях nginx по умолчанию использовались
<link doc="configuring_https_servers.xml" id="compatibility">другие</link>
шифры.
</note>
</para>

</directive>


<directive name="ssl_client_certificate">
<syntax><value>файл</value></syntax>
<default/>
<context>http</context>
<context>server</context>

<para>
Указывает <value>файл</value> с доверенными сертификатами CA в формате
PEM, которые используются для
<link id="ssl_verify_client">проверки</link> клиентских сертификатов и
ответов OCSP, если включён <link id="ssl_stapling"/>.
</para>

<para>
Список сертификатов будет отправляться клиентам.
Если это нежелательно, можно воспользоваться директивой
<link id="ssl_trusted_certificate"/>.
</para>

</directive>


<directive name="ssl_conf_command">
<syntax><value>имя</value> <value>значение</value></syntax>
<default/>
<context>http</context>
<context>server</context>
<appeared-in>1.19.4</appeared-in>

<para>
Задаёт произвольные конфигурационные
<link url="https://www.openssl.org/docs/man1.1.1/man3/SSL_CONF_cmd.html">команды</link>
OpenSSL.
<note>
Директива поддерживается при использовании OpenSSL 1.0.2 и выше.
</note>
</para>

<para>
На одном уровне может быть указано
несколько директив <literal>ssl_conf_command</literal>:
<example>
ssl_conf_command Options PrioritizeChaCha;
ssl_conf_command Ciphersuites TLS_CHACHA20_POLY1305_SHA256;
</example>
Директивы наследуются с предыдущего уровня конфигурации при условии, что
на данном уровне не описаны свои директивы <literal>ssl_conf_command</literal>.
</para>

<para>
<note>
Следует учитывать, что изменение настроек OpenSSL напрямую
может привести к неожиданному поведению.
</note>
</para>

</directive>


<directive name="ssl_crl">
<syntax><value>файл</value></syntax>
<default/>
<context>http</context>
<context>server</context>
<appeared-in>0.8.7</appeared-in>

<para>
Указывает <value>файл</value> с отозванными сертификатами (CRL)
в формате PEM, используемыми для
<link id="ssl_verify_client">проверки</link> клиентских сертификатов.
Если используются промежуточные сертификаты,
их списки CRL должны находиться в этом же файле.
</para>

</directive>


<directive name="ssl_dhparam">
<syntax><value>файл</value></syntax>
<default/>
<context>http</context>
<context>server</context>
<appeared-in>0.7.2</appeared-in>

<para>
Указывает <value>файл</value> с параметрами для DHE-шифров.
</para>

<para>
По умолчанию параметры не заданы,
и соответственно DHE-шифры не будут использоваться.
<note>
До версии 1.11.0 по умолчанию использовались встроенные параметры.
</note>
</para>

</directive>


<directive name="ssl_early_data">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<appeared-in>1.15.3</appeared-in>

<para>
Разрешает или запрещает TLS 1.3
<link url="https://datatracker.ietf.org/doc/html/rfc8446#section-2.3">early data</link>.
<note>
Директива поддерживается при использовании OpenSSL 1.1.1 и выше (1.15.4) или
<link url="https://boringssl.googlesource.com/boringssl/">BoringSSL</link>.
</note>
</para>

<para>
<note>
Запросы, отправленные внутри early data, могут быть подвержены
<link url="https://datatracker.ietf.org/doc/html/rfc8470">атакам повторного воспроизведения</link> (replay).
Для защиты от подобных атак на уровне приложения
необходимо использовать
переменную <link id="var_ssl_early_data">$ssl_early_data</link>.
</note>
<example>
proxy_set_header Early-Data $ssl_early_data;
</example>
</para>

<para>
<note>
Встроенная в OpenSSL защита от replay-атак отключена,
поскольку это препятствует возобновлению сессий.
При необходимости её можно включить обратно.
</note>
<example>
ssl_conf_command Options AntiReplay;
</example>
</para>

</directive>


<directive name="ssl_ecdh_curve">
<syntax><value>кривая</value></syntax>
<default>auto</default>
<context>http</context>
<context>server</context>
<appeared-in>1.1.0</appeared-in>
<appeared-in>1.0.6</appeared-in>

<para>
Задаёт кривую для ECDHE-шифров.
</para>

<para>
При использовании OpenSSL 1.0.2 и выше
можно указывать несколько кривых (1.11.0), например:
<example>
ssl_ecdh_curve prime256v1:secp384r1;
</example>
</para>

<para>
Специальное значение <literal>auto</literal> (1.11.0) соответствует
встроенному в библиотеку OpenSSL списку кривых для OpenSSL 1.0.2 и выше,
или <literal>prime256v1</literal> для более старых версий.
</para>

<para>
<note>
До версии 1.11.0
по умолчанию использовалась кривая <literal>prime256v1</literal>.
</note>
</para>

<para>
<note>
При использовании OpenSSL 1.0.2 и выше
директива задаёт список кривых, поддерживаемых сервером.
Поэтому для работы ECDSA-сертификатов
важно, чтобы список включал кривые, используемые в сертификатах.
</note>
</para>

</directive>


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

<para>
Задаёт <value>файл</value> с конфигурацией Encrypted ClientHello
(<literal>ECHConfig</literal>) в формате
<link url="https://datatracker.ietf.org/doc/draft-farrell-tls-pemesni/">PEM</link>,
используемой для включения TLS 1.3
<link url="https://datatracker.ietf.org/doc/html/draft-ietf-tls-esni">ECH</link>
в shared-режиме.
</para>

<para>
<note>
В настоящее время директива поддерживается только при использовании
<link url="https://github.com/openssl/openssl/tree/feature/ech">ветки
разработки ECH</link> OpenSSL.
</note>
</para>

</directive>


<directive name="ssl_key_log">
<syntax>путь</syntax>
<default/>
<context>http</context>
<context>server</context>
<appeared-in>1.27.2</appeared-in>

<para>
Включает логирование SSL-ключей клиентских соединений
и указывает путь к лог-файлу ключей.
Ключи записываются в формате
<link url="https://datatracker.ietf.org/doc/html/draft-ietf-tls-keylogfile">SSLKEYLOGFILE</link>
совместимом с Wireshark.
</para>

<para>
<note>
Директива доступна как часть
<commercial_version>коммерческой подписки</commercial_version>.
</note>
</para>

</directive>


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

<para>
Включает проверку OCSP для цепочки клиентских сертификатов.
Параметр <literal>leaf</literal>
включает проверку только клиентского сертификата.
</para>

<para>
Для работы проверки OCSP
необходимо дополнительно установить значение директивы
<link id="ssl_verify_client"/> в
<literal>on</literal> или <literal>optional</literal>.
</para>

<para>
Для преобразования имени хоста OCSP responder’а в адрес необходимо
дополнительно задать директиву
<link doc="ngx_http_core_module.xml" id="resolver"/>.
</para>

<para>
Пример:
<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>имя</value>:<value>размер</value>]</syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<appeared-in>1.19.0</appeared-in>

<para>
Задаёт <literal>имя</literal> и <literal>размер</literal> кэша,
который хранит статус клиентских сертификатов для проверки OCSP-ответов.
Кэш разделяется между всеми рабочими процессами.
Кэш с одинаковым названием может использоваться в нескольких
виртуальных серверах.
</para>

<para>
Параметр <literal>off</literal> запрещает использование кэша.
</para>

</directive>


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

<para>
Переопределяет URL OCSP responder’а, указанный в расширении сертификата
“<link url="https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.2.1">Authority
Information Access</link>”
для <link id="ssl_ocsp">проверки</link> клиентских сертификатов.
</para>

<para>
Поддерживаются только “<literal>http://</literal>” OCSP responder’ы:
<example>
ssl_ocsp_responder http://ocsp.example.com/;
</example>
</para>

</directive>


<directive name="ssl_password_file">
<syntax><value>файл</value></syntax>
<default/>
<context>http</context>
<context>server</context>
<appeared-in>1.7.3</appeared-in>

<para>
Задаёт <value>файл</value> с паролями от
<link id="ssl_certificate_key">секретных ключей</link>,
где каждый пароль указан на отдельной строке.
Пароли применяются по очереди в момент загрузки ключа.
</para>

<para>
Пример:
<example>
http {
    ssl_password_file /etc/keys/global.pass;
    ...

    server {
        server_name www1.example.com;
        ssl_certificate_key /etc/keys/first.key;
    }

    server {
        server_name www2.example.com;

        # вместо файла можно указать именованный канал
        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>http</context>
<context>server</context>

<para>
Указывает, чтобы при использовании протоколов SSLv3 и TLS
серверные шифры были более приоритетны, чем клиентские.
</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>http</context>
<context>server</context>

<para>
Разрешает указанные протоколы.
</para>

<para>
Если директива указана
на уровне <link doc="ngx_http_core_module.xml" id="server"/>,
то может использоваться значение из сервера по умолчанию.
Подробнее см. в разделе
“<link doc="server_names.xml" id="virtual_server_selection">Выбор
виртуального сервера</link>”.
</para>

<para>
<note>
Параметры <literal>TLSv1.1</literal> и <literal>TLSv1.2</literal>
(1.1.13, 1.0.12) работают только при использовании OpenSSL 1.0.1 и выше.
</note>
<note>
Параметр <literal>TLSv1.3</literal> (1.13.0) работает только
при использовании OpenSSL 1.1.1 и выше.
</note>
<note>
Параметр <literal>TLSv1.3</literal> используется по умолчанию
начиная с 1.23.4.
</note>
</para>

</directive>


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

<para>
Если разрешено, то операции SSL handshake в
блоке <link doc="ngx_http_core_module.xml" id="server"/> будут отклонены.
</para>

<para>
Например в этой конфигурации отклоняются все операции SSL handshake с
именем сервера, отличным от <literal>example.com</literal>:
<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>размер</value>]]
    [<literal>shared</literal>:<value>название</value>:<value>размер</value>]</syntax>
<default>none</default>
<context>http</context>
<context>server</context>

<para>
Задаёт тип и размеры кэшей для хранения параметров сессий.
Тип кэша может быть следующим:
<list type="tag">

<tag-name><literal>off</literal></tag-name>
<tag-desc>
жёсткое запрещение использования кэша сессий:
nginx явно сообщает клиенту, что сессии не могут использоваться повторно.
</tag-desc>

<tag-name><literal>none</literal></tag-name>
<tag-desc>
мягкое запрещение использования кэша сессий:
nginx сообщает клиенту, что сессии могут использоваться повторно, но
на самом деле не хранит параметры сессии в кэше.
</tag-desc>

<tag-name id="ssl_session_cache_builtin"><literal>builtin</literal></tag-name>
<tag-desc>
встроенный в OpenSSL кэш, используется в рамках только одного рабочего процесса.
Размер кэша задаётся в сессиях.
Если размер не задан, то он равен 20480 сессиям.
Использование встроенного кэша может вести к фрагментации памяти.
</tag-desc>

<tag-name id="ssl_session_cache_shared"><literal>shared</literal></tag-name>
<tag-desc>
кэш, разделяемый между всеми рабочими процессами.
Размер кэша задаётся в байтах, в 1 мегабайт может поместиться
около 4000 сессий.
У каждого разделяемого кэша должно быть произвольное название.
Кэш с одинаковым названием может использоваться в нескольких
виртуальных серверах.
Также он используется для автоматического создания, хранения и
периодического обновления ключей TLS session tickets (1.23.2),
если они не указаны явно
с помощью директивы <link id="ssl_session_ticket_key"/>.
</tag-desc>

</list>
</para>

<para>
Можно использовать одновременно оба типа кэша, например:
<example>
ssl_session_cache builtin:1000 shared:SSL:10m;
</example>
однако использование только разделяемого кэша без встроенного должно
быть более эффективным.
</para>

</directive>


<directive name="ssl_session_ticket_key">
<syntax><value>файл</value></syntax>
<default/>
<context>http</context>
<context>server</context>
<appeared-in>1.5.7</appeared-in>

<para>
Задаёт <value>файл</value> с секретным ключом, применяемым при шифровании и
расшифровании TLS session tickets.
Директива необходима, если один и тот же ключ нужно использовать
на нескольких серверах.
По умолчанию используется случайно сгенерированный ключ.
</para>

<para>
Если указано несколько ключей, то только первый ключ
используется для шифрования TLS session tickets.
Это позволяет настроить ротацию ключей, например:
<example>
ssl_session_ticket_key current.key;
ssl_session_ticket_key previous.key;
</example>
</para>

<para>
<value>Файл</value> должен содержать 80 или 48 байт случайных данных
и может быть создан следующей командой:
<example>
openssl rand 80 > ticket.key
</example>
В зависимости от размера файла для шифрования будет использоваться либо
AES256 (для 80-байтных ключей, 1.11.8), либо AES128 (для 48-байтных ключей).
</para>

</directive>


<directive name="ssl_session_tickets">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>on</default>
<context>http</context>
<context>server</context>
<appeared-in>1.5.9</appeared-in>

<para>
Разрешает или запрещает возобновление сессий при помощи
<link url="https://datatracker.ietf.org/doc/html/rfc5077">TLS session tickets</link>.
</para>

</directive>


<directive name="ssl_session_timeout">
<syntax><value>время</value></syntax>
<default>5m</default>
<context>http</context>
<context>server</context>

<para>
Задаёт время, в течение которого клиент может повторно
использовать параметры сессии.
</para>

</directive>


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

<para>
Разрешает или запрещает
<link url="https://datatracker.ietf.org/doc/html/rfc6066#section-8">прикрепление
OCSP-ответов</link> сервером.
Пример:
<example>
ssl_stapling on;
resolver 192.0.2.1;
</example>
</para>

<para>
Для работы OCSP stapling’а должен быть известен сертификат издателя
сертификата сервера.
Если в заданном директивой <link id="ssl_certificate"/>
файле не содержится промежуточных сертификатов,
то сертификат издателя сертификата сервера следует поместить в файл,
заданный директивой <link id="ssl_trusted_certificate"/>.
</para>

<para>
Для преобразования имени хоста OCSP responder’а в адрес необходимо
дополнительно задать директиву
<link doc="ngx_http_core_module.xml" id="resolver"/>.
</para>

</directive>


<directive name="ssl_stapling_file">
<syntax><value>файл</value></syntax>
<default/>
<context>http</context>
<context>server</context>
<appeared-in>1.3.7</appeared-in>

<para>
Если задано, то вместо опроса OCSP responder’а,
указанного в сертификате сервера,
ответ берётся из указанного <value>файла</value>.
</para>

<para>
Ответ должен быть в формате DER и может быть сгенерирован командой
“<literal>openssl ocsp</literal>”.
</para>

</directive>


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

<para>
Переопределяет URL OCSP responder’а, указанный в расширении сертификата
“<link url="https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.2.1">Authority
Information Access</link>”.
</para>

<para>
Поддерживаются только “<literal>http://</literal>” OCSP responder’ы:
<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>http</context>
<context>server</context>
<appeared-in>1.3.7</appeared-in>

<para>
Разрешает или запрещает проверку сервером ответов OCSP.
</para>

<para>
Для работоспособности проверки сертификат издателя сертификата сервера,
корневой сертификат и все промежуточные сертификаты должны быть указаны
как доверенные с помощью директивы
<link id="ssl_trusted_certificate"/>.
</para>

</directive>


<directive name="ssl_trusted_certificate">
<syntax><value>файл</value></syntax>
<default/>
<context>http</context>
<context>server</context>
<appeared-in>1.3.7</appeared-in>

<para>
Задаёт <value>файл</value> с доверенными сертификатами CA в формате PEM,
которые используются для <link id="ssl_verify_client">проверки</link>
клиентских сертификатов и ответов OCSP,
если включён <link id="ssl_stapling"/>.
</para>

<para>
В отличие от <link id="ssl_client_certificate"/>, список этих сертификатов
не будет отправляться клиентам.
</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>http</context>
<context>server</context>

<para>
Разрешает проверку клиентских сертификатов.
Результат проверки доступен через переменную
<link id="var_ssl_client_verify">$ssl_client_verify</link>.
</para>

<para>
Параметр <literal>optional</literal> (0.8.7+) запрашивает клиентский
сертификат, и если сертификат был предоставлен, проверяет его.
</para>

<para>
Параметр <literal>optional_no_ca</literal> (1.3.8, 1.2.5)
запрашивает сертификат
клиента, но не требует, чтобы он был подписан доверенным сертификатом CA.
Это предназначено для случаев, когда фактическая проверка сертификата
осуществляется внешним по отношению к nginx’у сервисом.
Содержимое сертификата доступно через переменную
<link id="var_ssl_client_cert">$ssl_client_cert</link>.
</para>

</directive>


<directive name="ssl_verify_depth">
<syntax><value>число</value></syntax>
<default>1</default>
<context>http</context>
<context>server</context>

<para>
Устанавливает глубину проверки в цепочке клиентских сертификатов.
</para>

</directive>

</section>


<section id="errors" name="Обработка ошибок">

<para>
Модуль <literal>ngx_http_ssl_module</literal> поддерживает несколько
нестандартных кодов ошибок, которые можно использовать для
перенаправления с помощью директивы
<link doc="ngx_http_core_module.xml" id="error_page"/>:
<list type="tag">

<tag-name>495</tag-name>
<tag-desc>
при проверке клиентского сертификата произошла ошибка;
</tag-desc>

<tag-name>496</tag-name>
<tag-desc>
клиент не предоставил требуемый сертификат;
</tag-desc>

<tag-name>497</tag-name>
<tag-desc>
обычный запрос был послан на порт HTTPS.
</tag-desc>

</list>
</para>

<para>
Перенаправление делается после того, как запрос полностью разобран
и доступны такие переменные, как <var>$request_uri</var>,
<var>$uri</var>, <var>$args</var> и другие переменные.
</para>

</section>


<section id="variables" name="Встроенные переменные">

<para>
Модуль <literal>ngx_http_ssl_module</literal> поддерживает
встроенные переменные:
<list type="tag">

<tag-name id="var_ssl_alpn_protocol"><var>$ssl_alpn_protocol</var></tag-name>
<tag-desc>
возвращает протокол, выбранный при помощи ALPN во время операции SSL handshake,
либо пустую строку (1.21.4);
</tag-desc>

<tag-name id="var_ssl_cipher"><var>$ssl_cipher</var></tag-name>
<tag-desc>
возвращает название используемого шифра для установленного SSL-соединения;
</tag-desc>

<tag-name id="var_ssl_ciphers"><var>$ssl_ciphers</var></tag-name>
<tag-desc>
возвращает список шифров, поддерживаемых клиентом (1.11.7).
Известные шифры указаны по имени, неизвестные указаны в шестнадцатеричном виде,
например:
<example>
AES128-SHA:AES256-SHA:0x00ff
</example>
<note>
Переменная полностью поддерживается при использовании OpenSSL версии 1.0.2
и выше.
При использовании более старых версий переменная доступна
только для новых сессий и может содержать только известные шифры.
</note>
</tag-desc>

<tag-name id="var_ssl_client_escaped_cert"><var>$ssl_client_escaped_cert</var></tag-name>
<tag-desc>
возвращает клиентский сертификат в формате PEM
(закодирован в формате urlencode) для установленного SSL-соединения (1.13.5);
</tag-desc>

<tag-name id="var_ssl_client_cert"><var>$ssl_client_cert</var></tag-name>
<tag-desc>
возвращает клиентский сертификат в формате PEM
для установленного SSL-соединения, перед каждой строкой которого, кроме первой,
вставляется символ табуляции;
предназначена для использования в директиве
<link doc="ngx_http_proxy_module.xml" id="proxy_set_header"/>;
<note>
Переменная устарела, вместо неё следует использовать
переменную <var>$ssl_client_escaped_cert</var>.
</note>
</tag-desc>

<tag-name id="var_ssl_client_fingerprint"><var>$ssl_client_fingerprint</var></tag-name>
<tag-desc>
возвращает SHA1-отпечаток клиентского сертификата
для установленного SSL-соединения (1.7.1);
</tag-desc>

<tag-name id="var_ssl_client_i_dn"><var>$ssl_client_i_dn</var></tag-name>
<tag-desc>
возвращает строку “issuer DN” клиентского сертификата
для установленного SSL-соединения согласно
<link url="https://datatracker.ietf.org/doc/html/rfc2253">RFC 2253</link> (1.11.6);
</tag-desc>

<tag-name id="var_ssl_client_i_dn_legacy"><var>$ssl_client_i_dn_legacy</var></tag-name>
<tag-desc>
возвращает строку “issuer DN” клиентского сертификата
для установленного SSL-соединения;
<note>
До версии 1.11.6 переменная называлась <var>$ssl_client_s_dn</var>.
</note>
</tag-desc>

<tag-name id="var_ssl_client_raw_cert"><var>$ssl_client_raw_cert</var>
</tag-name>
<tag-desc>
возвращает клиентский сертификат в формате PEM
для установленного SSL-соединения;
</tag-desc>

<tag-name id="var_ssl_client_s_dn"><var>$ssl_client_s_dn</var></tag-name>
<tag-desc>
возвращает строку “subject DN” клиентского сертификата
для установленного SSL-соединения согласно
<link url="https://datatracker.ietf.org/doc/html/rfc2253">RFC 2253</link> (1.11.6);
</tag-desc>

<tag-name id="var_ssl_client_s_dn_legacy"><var>$ssl_client_s_dn_legacy</var></tag-name>
<tag-desc>
возвращает строку “subject DN” клиентского сертификата
для установленного SSL-соединения;
<note>
До версии 1.11.6 переменная называлась <var>$ssl_client_s_dn</var>.
</note>
</tag-desc>

<tag-name id="var_ssl_client_serial"><var>$ssl_client_serial</var></tag-name>
<tag-desc>
возвращает серийный номер клиентского сертификата
для установленного SSL-соединения;
</tag-desc>

<tag-name id="var_ssl_client_sigalg"><var>$ssl_client_sigalg</var></tag-name>
<tag-desc>
возвращает
<link url="https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-16">алгоритм подписи</link>
клиентского сертификата для установленного SSL-соединения (1.29.3).
<note>
Переменная поддерживается при использовании OpenSSL версии 3.5 и выше.
При использовании более старых версий значением переменной будет пустая строка.
</note>
<note>
Переменная доступна только для новых сессий.
</note>
</tag-desc>

<tag-name id="var_ssl_client_v_end"><var>$ssl_client_v_end</var></tag-name>
<tag-desc>
возвращает дату окончания срока действия клиентского сертификата (1.11.7);
</tag-desc>

<tag-name id="var_ssl_client_v_remain"><var>$ssl_client_v_remain</var></tag-name>
<tag-desc>
возвращает число дней,
оставшихся до истечения срока действия клиентского сертификата (1.11.7);
</tag-desc>

<tag-name id="var_ssl_client_v_start"><var>$ssl_client_v_start</var></tag-name>
<tag-desc>
возвращает дату начала срока действия клиентского сертификата (1.11.7);
</tag-desc>

<tag-name id="var_ssl_client_verify"><var>$ssl_client_verify</var></tag-name>
<tag-desc>
возвращает результат проверки клиентского сертификата:
“<literal>SUCCESS</literal>”, “<literal>FAILED:</literal><value>reason</value>”
и, если сертификат не был предоставлен, “<literal>NONE</literal>”;
<note>
До версии 1.11.7 результат “<literal>FAILED</literal>”
не содержал строку <value>reason</value>.
</note>
</tag-desc>

<tag-name id="var_ssl_curve"><var>$ssl_curve</var></tag-name>
<tag-desc>
возвращает согласованную кривую, использованную для
обмена ключами во время операции SSL handshake (1.21.5).
Известные кривые указаны по имени, неизвестные указаны в шестнадцатеричном виде,
например:
<example>
prime256v1
</example>
<note>
Переменная поддерживается при использовании OpenSSL версии 3.0 и выше.
При использовании более старых версий значением переменной будет пустая строка.
</note>
</tag-desc>

<tag-name id="var_ssl_curves"><var>$ssl_curves</var></tag-name>
<tag-desc>
возвращает список кривых, поддерживаемых клиентом (1.11.7).
Известные кривые указаны по имени, неизвестные указаны в шестнадцатеричном виде,
например:
<example>
0x001d:prime256v1:secp521r1:secp384r1
</example>
<note>
Переменная поддерживается при использовании OpenSSL версии 1.0.2 и выше.
При использовании более старых версий значением переменной будет пустая строка.
</note>
<note>
Переменная доступна только для новых сессий.
</note>
</tag-desc>

<tag-name id="var_ssl_early_data"><var>$ssl_early_data</var></tag-name>
<tag-desc>
возвращает “<literal>1</literal>”, если
используется TLS 1.3 <link id="ssl_early_data">early data</link>
и операция handshake не завершена, иначе “” (1.15.3).
</tag-desc>

<tag-name id="var_ssl_ech_outer_server_name"><var>$ssl_ech_outer_server_name</var></tag-name>
<tag-desc>
возвращает публичное имя сервера, запрошенное через
<link url="http://en.wikipedia.org/wiki/Server_Name_Indication">SNI</link>
если TLS 1.3 <link id="ssl_ech_file">ECH</link> был принят,
иначе “” (1.29.4);
</tag-desc>

<tag-name id="var_ssl_ech_status"><var>$ssl_ech_status</var></tag-name>
<tag-desc>
возвращает результат обработки TLS 1.3 <link id="ssl_ech_file">ECH</link>:
“<literal>FAILED</literal>”,
“<literal>BACKEND</literal>”,
“<literal>GREASE</literal>”,
“<literal>SUCCESS</literal>” или
“<literal>NOT_TRIED</literal>” (1.29.4);
<note>
В настоящее время переменная поддерживается при использовании
<link url="https://github.com/openssl/openssl/tree/feature/ech">ветки разработки ECH</link>
и, таким образом, может измениться.
В остальных случаях значением переменной будет пустая строка.
</note>
</tag-desc>

<tag-name id="var_ssl_protocol"><var>$ssl_protocol</var></tag-name>
<tag-desc>
возвращает протокол установленного SSL-соединения;
</tag-desc>

<tag-name id="var_ssl_server_name"><var>$ssl_server_name</var></tag-name>
<tag-desc>
возвращает имя сервера, запрошенное через
<link url="http://en.wikipedia.org/wiki/Server_Name_Indication">SNI</link>
(1.7.0);
</tag-desc>

<tag-name id="var_ssl_session_id"><var>$ssl_session_id</var></tag-name>
<tag-desc>
возвращает идентификатор сессии установленного SSL-соединения;
</tag-desc>

<tag-name id="var_ssl_session_reused"><var>$ssl_session_reused</var></tag-name>
<tag-desc>
возвращает “<literal>r</literal>”, если сессия была использована повторно,
иначе “<literal>.</literal>” (1.5.11).
</tag-desc>

<tag-name id="var_ssl_sigalg"><var>$ssl_sigalg</var></tag-name>
<tag-desc>
возвращает
<link url="https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-16">алгоритм подписи</link>
сертификата сервера для установленного SSL-соединения (1.29.3).
<note>
Переменная поддерживается при использовании OpenSSL версии 3.5 и выше.
При использовании более старых версий значением переменной будет пустая строка.
</note>
<note>
Переменная доступна только для новых сессий.
</note>
</tag-desc>

</list>
</para>

</section>

</module>