<?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="11">

<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>
установить число рабочих процессов равным числу процессоров,
</listitem>

<listitem>
разрешить keep-alive соединения,
</listitem>

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

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

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

</list>

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

http {

    ...

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

        ssl_protocols       SSLv3 TLSv1 TLSv1.1 TLSv1.2;
        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>
Включает протокол HTTPS для данного виртуального сервера.
<note>
Вместо этой директивы рекомендуется использовать параметр
<literal>ssl</literal> директивы
<link doc="ngx_http_core_module.xml" id="listen"/>.
</note>
</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>
Нужно иметь в виду, что из-за ограничения протокола HTTPS
виртуальные серверы должны слушать на разных IP-адресах:
<example>
server {
    listen          192.168.1.1:443;
    server_name     one.example.com;
    ssl_certificate /usr/local/nginx/conf/one.example.com.cert;
    ...
}

server {
    listen          192.168.1.2:443;
    server_name     two.example.com;
    ssl_certificate /usr/local/nginx/conf/two.example.com.cert;
    ...
}
</example>
иначе для второго сайта будет выдаваться
<link doc="configuring_https_servers.xml"
    id="name_based_https_servers">сертификат первого сервера</link>.
</para>

</directive>


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

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

<para>
Список сертификатов будет отправляться клиентам.
Если это нежелательно, можно воспользоваться директивой
<link id="ssl_trusted_certificate"/>.
</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, используемыми для проверки клиентских сертификатов.
</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> с параметрами для шифров с обменом EDH-ключами.
</para>

</directive>


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

<para>
Задаёт кривую для ECDHE-шифров.
</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>]</syntax>
<default>SSLv3 TLSv1 TLSv1.1 TLSv1.2</default>
<context>http</context>
<context>server</context>

<para>
Разрешает указанные протоколы.
Параметры <literal>TLSv1.1</literal> и <literal>TLSv1.2</literal> работают
только при использовании библиотеки OpenSSL версии 1.0.1 и выше.
<note>
Параметры <literal>TLSv1.1</literal> и <literal>TLSv1.2</literal> поддерживаются
только начиная с версий 1.1.13 и 1.0.12,
поэтому при использовании OpenSSL версии 1.0.1
и выше на старых версиях nginx эти протоколы работать будут, однако их нельзя
будет отключить.
</note>
</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><literal>builtin</literal></tag-name>
<tag-desc>
встроенный в OpenSSL кэш, используется в рамках только одного рабочего процесса.
Размер кэша задаётся в сессиях.
Если размер не задан, то он равен 20480 сессиям.
Использование встроенного кэша может вести к фрагментации памяти.
</tag-desc>

<tag-name><literal>shared</literal></tag-name>
<tag-desc>
кэш, разделяемый между всеми рабочими процессами.
Размер кэша задаётся в байтах, в 1 мегабайт может поместиться
около 4000 сессий.
У каждого разделяемого кэша должно быть произвольное название.
Кэш с одинаковым названием может использоваться в нескольких
виртуальных серверах.
</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> должен содержать 48 байт случайных данных и может быть
создан следующей командой:
<example>
openssl rand 48 > ticket.key
</example>
</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="http://tools.ietf.org/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="http://tools.ietf.org/html/rfc4366#section-3.6">прикрепление
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="http://tools.ietf.org/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,
которые используются для проверки клиентских сертификатов и ответов 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>
Разрешает проверку клиентских сертификатов.
Результат проверки доступен через переменную
<var>$ssl_client_verify</var>.
</para>

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

<para>
Параметр <literal>optional_no_ca</literal> (1.3.8, 1.2.5)
запрашивает сертификат
клиента, но не требует, чтобы он был подписан доверенным сертификатом CA.
Это предназначено для случаев, когда фактическая проверка сертификата
осуществляется внешним по отношению к nginx’у сервисом.
Содержимое сертификата доступно через переменную
<var>$ssl_client_cert</var>.
</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><var>$ssl_cipher</var></tag-name>
<tag-desc>
возвращает строку используемых шифров для установленного SSL-соединения;
</tag-desc>

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

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

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

<tag-name><var>$ssl_client_s_dn</var></tag-name>
<tag-desc>
возвращает строку “subject DN” клиентского сертификата
для установленного SSL-соединения;
</tag-desc>

<tag-name><var>$ssl_client_i_dn</var></tag-name>
<tag-desc>
возвращает строку “issuer DN” клиентского сертификата
для установленного SSL-соединения;
</tag-desc>

<tag-name><var>$ssl_client_verify</var></tag-name>
<tag-desc>
возвращает результат проверки клиентского сертификата:
“<literal>SUCCESS</literal>”, “<literal>FAILED</literal>” и,
если сертификат не был предоставлен — “<literal>NONE</literal>”;
</tag-desc>

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

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

</list>
</para>

</section>

</module>