Модуль ngx_http_ssl_module

• Пример конфигурации
• Директивы
• ssl
• ssl_buffer_size
• ssl_certificate
• ssl_certificate_key
• ssl_ciphers
• ssl_client_certificate
• ssl_conf_command
• ssl_crl
• ssl_dhparam
• ssl_early_data
• ssl_ecdh_curve
• ssl_ocsp
• ssl_ocsp_cache
• ssl_ocsp_responder
• ssl_password_file
• ssl_prefer_server_ciphers
• ssl_protocols
• ssl_reject_handshake
• ssl_session_cache
• ssl_session_ticket_key
• ssl_session_tickets
• ssl_session_timeout
• ssl_stapling
• ssl_stapling_file
• ssl_stapling_responder
• ssl_stapling_verify
• ssl_trusted_certificate
• ssl_verify_client
• ssl_verify_depth
• Обработка ошибок
• Встроенные переменные

Модуль ngx_http_ssl_module предоставляет необходимую поддержку HTTPS.

Этот модуль не компилируется по умолчанию, его необходимо включить с помощью параметра конфигурации --with-http_ssl_module.

Для работы этого модуля требуется библиотека OpenSSL.

Пример конфигурации

Для снижения нагрузки процессора рекомендуется

• установить количество рабочих процессов равное количеству процессоров,
• включить keep-alive соединения,
• включить общий кэш сессий,
• отключить встроенный кэш сессий,
• и, возможно, увеличить время жизни сессии (по умолчанию 5 минут):

worker_processes auto;

http {

    ...

    server {
        listen              443 ssl;
        keepalive_timeout   70;

        ssl_protocols       TLSv1 TLSv1.1 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;
        ssl_session_cache   shared:SSL:10m;
        ssl_session_timeout 10m;

        ...
    }

Директивы

Эта директива устарела в версии 1.15.0 и была удалена в версии 1.25.1. Вместо неё следует использовать параметр ssl директивы listen.

Устанавливает размер буфера, используемого для отправки данных.

По умолчанию размер буфера составляет 16 КБ, что соответствует минимальной дополнительной нагрузке при отправке больших ответов. Для минимизации времени до первой байтовой отправки (TTFB) может быть полезно использовать меньшие значения, например:

ssl_buffer_size 4k;

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

С версии 1.11.0, эта директива может быть указана несколько раз для загрузки сертификатов разных типов, например, RSA и ECDSA:

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;

    ...
}

Только OpenSSL 1.0.2 или выше поддерживает отдельные цепочки сертификатов для разных сертификатов. С более старыми версиями может быть использована только одна цепочка сертификатов.

С версии 1.15.9, в имени file можно использовать переменные при использовании OpenSSL 1.0.2 или выше:

ssl_certificate     $ssl_server_name.crt;
ssl_certificate_key $ssl_server_name.key;

Обратите внимание, что использование переменных подразумевает загрузку сертификата для каждого SSL-рукопожатия, и это может негативно сказаться на производительности.

Вместо file (1.15.10) можно указать значение data:$variable, что загружает сертификат из переменной без использования промежуточных файлов. Обратите внимание, что неправильное использование этого синтаксиса может иметь последствия для безопасности, например, запись данных секретного ключа в журнал ошибок.

Следует помнить, что из-за ограничений протокола HTTPS для максимальной совместимости виртуальные сервера должны слушать на различных IP-адресах.

Указывает file с секретным ключом в формате PEM для данного виртуального сервера.

Вместо file (1.7.9) можно указать значение engine:name:id, что загружает секретный ключ с указанным id из модуля OpenSSL name.

Вместо file (1.15.10) можно указать значение data:$variable, что загружает секретный ключ из переменной без использования промежуточных файлов. Обратите внимание, что неправильное использование этого синтаксиса может иметь последствия для безопасности, например, запись данных секретного ключа в журнал ошибок.

С версии 1.15.9, в имени file можно использовать переменные при использовании OpenSSL 1.0.2 или выше.

Указывает поддерживаемые шифры. Шифры указываются в формате, понятном библиотеке OpenSSL, например:

ssl_ciphers ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;

Полный список можно посмотреть, используя команду «openssl ciphers».

Предыдущие версии nginx использовали другие шифры по умолчанию.

Указывает файл file с доверенными сертификатами CA в формате PEM, используемый для проверки сертификатов клиентов и ответов OCSP, если включен ssl_stapling.

Список сертификатов будет отправлен клиентам. Если этого не требуется, можно использовать директиву ssl_trusted_certificate.

Устанавливает произвольные конфигурационные команды OpenSSL команды.

Директива поддерживается при использовании OpenSSL 1.0.2 или выше.

Несколько директивы ssl_conf_command могут быть указаны на одном уровне:

ssl_conf_command Options PrioritizeChaCha;
ssl_conf_command Ciphersuites TLS_CHACHA20_POLY1305_SHA256;

Эти директивы наследуются с предыдущего уровня конфигурации только в том случае, если на текущем уровне нет определенных директивы ssl_conf_command.

Обратите внимание, что непосредственная конфигурация OpenSSL может привести к неожиданному поведению.

Указывает файл file с отмененными сертификатами (CRL) в формате PEM, используемый для проверки сертификатов клиентов.

Указывает файл file с параметрами DH для шифров DHE.

По умолчанию параметры не устанавливаются, и поэтому шифры DHE не будут использоваться.

До версии 1.11.0 по умолчанию использовались встроенные параметры.

Включает или отключает TLS 1.3 ранние данные.

Запросы, отправленные в рамках ранних данных, подвержены атакам повторения. Для защиты от таких атак на уровне приложения следует использовать переменную $ssl_early_data.

proxy_set_header Early-Data $ssl_early_data;

Директива поддерживается при использовании OpenSSL 1.1.1 или выше (1.15.4) и BoringSSL.

Указывает кривую curve для шифров ECDHE.

При использовании OpenSSL 1.0.2 или выше, можно указать несколько кривых (1.11.0), например:

ssl_ecdh_curve prime256v1:secp384r1;

Специальное значение auto (1.11.0) указывает nginx на использование списка, встроенного в библиотеку OpenSSL при использовании OpenSSL 1.0.2 или выше, или prime256v1 с более старыми версиями.

До версии 1.11.0 по умолчанию использовалась кривая prime256v1.

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

Включает проверку OCSP цепочки сертификатов клиента. Параметр leaf включает проверку только сертификата клиента.

Для работы проверки OCSP директива ssl_verify_client должна быть установлена в значение on или optional.

Для разрешения имени хоста OCSP-отправителя также должна быть указана директива resolver.

Пример:

ssl_verify_client on;
ssl_ocsp          on;
resolver          192.0.2.1;

Устанавливает name и size кэша, который хранит статус сертификатов клиентов для проверки OCSP. Кэш общий для всех процессов-работников. Кэш с тем же именем может использоваться в нескольких виртуальных серверах.

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

Переопределяет URL OCSP-отправителя, указанный в расширении сертификата «Authority Information Access» для проверки сертификатов клиентов.

Поддерживаются только OCSP-отправители «http://»:

ssl_ocsp_responder http://ocsp.example.com/;

Указывает файл file с паролями для секретных ключей, где каждый пароль указан на отдельной строке. Пароли пробуются по очереди при загрузке ключа.

Пример:

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;

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

Указывает, что при использовании протоколов SSLv3 и TLS должны предпочтительно использоваться шифры сервера, а не клиента.

Включает указанные протоколы.

Если директива указана на уровне сервера, то используется значение от сервера по умолчанию. Подробности см. в разделе «Выбор виртуального сервера».

Параметры TLSv1.1 и TLSv1.2 (1.1.13, 1.0.12) работают только при использовании OpenSSL 1.0.1 или выше.

Параметр TLSv1.3 (1.13.0) работает только при использовании OpenSSL 1.1.1 или выше.

Параметр TLSv1.3 используется по умолчанию с 1.23.4.

Если включено, то рукопожатия SSL в блоке сервера будут отклонены.

Например, в следующей конфигурации отклоняются рукопожатия SSL с именами сервера, отличными от example.com:

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

Устанавливает типы и размеры кэшей, хранящих параметры сессии. Кэш может быть любого из следующих типов:

off

использование кэша сессий строго запрещено: nginx явно сообщает клиенту, что сессии не могут быть повторно использованы.

none

использование кэша сессий мягко запрещено: nginx сообщает клиенту, что сессии могут быть повторно использованы, но не фактически хранит параметры сессии в кэше.

builtin

кэш, встроенный в OpenSSL; используется только одним процессом-работником. Размер кэша задаётся в сессиях. Если размер не указан, он равен 20480 сессиям. Использование встроенного кэша может привести к фрагментации памяти.

shared

кэш, общий для всех процессов-работников. Размер кэша задаётся в байтах; один мегабайт может хранить около 4000 сессий. Каждый общий кэш должен иметь произвольное имя. Кэш с тем же именем может использоваться в нескольких виртуальных серверах. Также используется для автоматического создания, хранения и периодической смены ключей билетов TLS-сессии (1.23.2), если не настроено явно с помощью директивы ssl_session_ticket_key.

Оба типа кэшей могут использоваться одновременно, например:

ssl_session_cache builtin:1000 shared:SSL:10m;

но использование только общего кэша без встроенного кэша должно быть более эффективным.

Устанавливает file с секретным ключом, используемым для шифрования и дешифрования билетов TLS-сессий. Директива необходима, если один и тот же ключ должен использоваться между несколькими серверами. По умолчанию используется случайный ключ.

Если указано несколько ключей, используется только первый ключ для шифрования билетов TLS-сессий. Это позволяет настроить смену ключей, например:

ssl_session_ticket_key current.key;
ssl_session_ticket_key previous.key;

Файл file должен содержать 80 или 48 байт случайных данных и может быть создан с помощью следующей команды:

openssl rand 80 > ticket.key

В зависимости от размера файла используется либо AES256 (для 80-байтовых ключей, 1.11.8), либо AES128 (для 48-байтовых ключей) для шифрования.

ssl_stapling on;
resolver 192.0.2.1;

Заменяет URL OCSP-ответчика, указанный в расширении сертификата «Доступ к информации об авторитете».

Поддерживаются только OCSP-ответчики типа «http://»:

ssl_stapling_responder http://ocsp.example.com/;

Включает или отключает проверку OCSP-ответов сервером.

Для работы проверки, сертификат издателя сертификата сервера, корневой сертификат и все промежуточные сертификаты должны быть настроены как доверенные с помощью директивы ssl_trusted_certificate.

Указывает file с доверенными сертификатами CA в формате PEM, используемом для проверки сертификатов клиентов и OCSP-ответов, если включен ssl_stapling.

В отличие от набора сертификатов, заданного с помощью ssl_client_certificate, список этих сертификатов не будет отправлен клиентам.

Включает проверку сертификатов клиентов. Результат проверки хранится в переменной $ssl_client_verify.

Параметр optional (0.8.7+) запрашивает сертификат клиента и проверяет его, если сертификат есть.

Параметр optional_no_ca (1.3.8, 1.2.5) запрашивает сертификат клиента, но не требует, чтобы он был подписан доверенным сертификатом CA. Это предназначено для случаев, когда внешняя служба выполняет фактическую проверку сертификата. Содержимое сертификата доступно через переменную $ssl_client_cert.

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

Обработка ошибок

Модуль ngx_http_ssl_module поддерживает несколько нестандартных кодов ошибок, которые могут использоваться для перенаправлений с помощью директивы error_page:

495

произошла ошибка во время проверки сертификата клиента;

496

клиент не предоставил требуемый сертификат;

497

обычный запрос отправлен на порт HTTPS.

Перенаправление происходит после полной обработки запроса и доступности переменных, таких как $request_uri, $uri, $args и других.

Встроенные переменные

Модуль ngx_http_ssl_module поддерживает встроенные переменные:

$ssl_alpn_protocol

возвращает протокол, выбранный ALPN во время рукопожатия SSL, или пустую строку в противном случае (1.21.4);

$ssl_cipher

возвращает имя шифра, используемого для установленного SSL-соединения;

$ssl_ciphers

возвращает список шифров, поддерживаемых клиентом (1.11.7). Известные шифры перечислены по именам, неизвестные — в шестнадцатеричном формате, например:

AES128-SHA:AES256-SHA:0x00ff

Переменная полностью поддерживается только при использовании OpenSSL версии 1.0.2 или выше. С более старыми версиями переменная доступна только для новых сеансов и перечисляет только известные шифры.

$ssl_client_escaped_cert

возвращает сертификат клиента в формате PEM (urlencoded) для установленного SSL-соединения (1.13.5);

$ssl_client_cert

возвращает сертификат клиента в формате PEM для установленного SSL-соединения, при этом каждая строка, кроме первой, дополняется символом табуляции; это предназначено для использования в директиве proxy_set_header;

Переменная устарела, следует использовать переменную $ssl_client_escaped_cert вместо неё.

$ssl_client_fingerprint

возвращает SHA1 отпечаток сертификата клиента для установленного SSL-соединения (1.7.1);

$ssl_client_i_dn

возвращает строку «issuer DN» сертификата клиента для установленного SSL-соединения в соответствии с RFC 2253 (1.11.6);

$ssl_client_i_dn_legacy

возвращает строку «issuer DN» сертификата клиента для установленного SSL-соединения;

До версии 1.11.6 имя переменной было $ssl_client_i_dn.

$ssl_client_raw_cert

возвращает сертификат клиента в формате PEM для установленного SSL-соединения;

$ssl_client_s_dn

возвращает строку «subject DN» сертификата клиента для установленного SSL-соединения в соответствии с RFC 2253 (1.11.6);

$ssl_client_s_dn_legacy

возвращает строку «subject DN» сертификата клиента для установленного SSL-соединения;

До версии 1.11.6 имя переменной было $ssl_client_s_dn.

$ssl_client_serial

возвращает серийный номер сертификата клиента для установленного SSL-соединения;

$ssl_client_v_end

возвращает конечную дату сертификата клиента (1.11.7);

$ssl_client_v_remain

возвращает количество дней до истечения срока действия сертификата клиента (1.11.7);

$ssl_client_v_start

возвращает начальную дату сертификата клиента (1.11.7);

$ssl_client_verify

возвращает результат проверки сертификата клиента: «SUCCESS», «FAILED:reason», и «NONE», если сертификат отсутствовал;

До версии 1.11.7 результат «FAILED» не содержал строку reason.

$ssl_curve

возвращает выбранную кривую, используемую для обмена ключами SSL-соединения (1.21.5). Известные кривые перечислены по именам, неизвестные — в шестнадцатеричном формате, например:

prime256v1

Переменная поддерживается только при использовании OpenSSL версии 3.0 или выше. С более старыми версиями значение переменной будет пустой строкой.

$ssl_curves

возвращает список кривых, поддерживаемых клиентом (1.11.7). Известные кривые перечислены по именам, неизвестные — в шестнадцатеричном формате, например:

0x001d:prime256v1:secp521r1:secp384r1

Переменная поддерживается только при использовании OpenSSL версии 1.0.2 или выше. С более старыми версиями значение переменной будет пустой строкой.

Переменная доступна только для новых сеансов.

$ssl_early_data

возвращает «1», если используется TLS 1.3 ранние данные и рукопожатие не завершено, в противном случае «» (1.15.3).

$ssl_protocol

возвращает протокол установленного SSL-соединения;

$ssl_server_name

возвращает имя сервера, запрошенное через SNI (1.7.0);

$ssl_session_id

возвращает идентификатор сессии установленного SSL-соединения;

$ssl_session_reused

возвращает «r», если SSL-сессия была повторно использована, или «.» в противном случае (1.5.11).