Модуль ngx_stream_ssl_module

Модуль ngx_stream_ssl_module (1.9.0) обеспечивает необходимую поддержку для работы прокси-сервера по протоколу SSL/TLS. По умолчанию этот модуль не собирается, его сборку необходимо разрешить с помощью конфигурационного параметра --with-stream_ssl_module.

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

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

worker_processes auto;

stream {

    ...

    server {
        listen              12345 ssl;

        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;

        ...
    }

Задаёт список поддерживаемых протоколов ALPN. Один из протоколов должен быть согласован, если клиент использует ALPN:

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

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

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

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;

    ...
}

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

Начиная с версии 1.15.9 в имени файла можно использовать переменные при использовании OpenSSL 1.0.2 и выше:

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

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

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

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

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

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

Начиная с версии 1.15.9 в имени файла можно использовать переменные при использовании OpenSSL 1.0.2 и выше.

ssl_ciphers HIGH:!aNULL:!MD5;

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

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

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

Указывает файл с доверенными сертификатами 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 напрямую может привести к неожиданному поведению.

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

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

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

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

ssl_ecdh_curve auto;

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

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

ssl_ecdh_curve prime256v1:secp384r1;

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

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

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

ssl_handshake_timeout 60s;

Задаёт таймаут для завершения операции SSL handshake.

Включает логирование SSL-ключей клиентских соединений и указывает путь к лог-файлу ключей. Ключи записываются в формате SSLKEYLOGFILE совместимом с Wireshark.

Директива доступна как часть коммерческой подписки.

ssl_ocsp off;

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

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

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

Пример:

ssl_verify_client on;
ssl_ocsp          on;
resolver          192.0.2.1;

ssl_ocsp_cache off;

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

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

Переопределяет URL OCSP responder’а, указанный в расширении сертификата “Authority Information Access” для проверки клиентских сертификатов.

Поддерживаются только “http://” OCSP responder’ы:

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

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

Пример:

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;

        # вместо файла можно указать именованный канал
        ssl_password_file /etc/keys/fifo;
        ssl_certificate_key /etc/keys/second.key;
    }
}

ssl_prefer_server_ciphers off;

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

ssl_protocols TLSv1 TLSv1.1 TLSv1.2 TLSv1.3;

Разрешает указанные протоколы.

Если директива указана на уровне server, то может использоваться значение из сервера по умолчанию.

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

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

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

ssl_reject_handshake off;

Если разрешено, то операции SSL handshake в блоке server будут отклонены.

Например в этой конфигурации отклоняются все операции SSL handshake с именем сервера, отличным от 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;
}

ssl_session_cache none;

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

off

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

none

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

builtin

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

shared

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

Можно использовать одновременно оба типа кэша, например:

ssl_session_cache builtin:1000 shared:SSL:10m;

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

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

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

ssl_session_ticket_key current.key;
ssl_session_ticket_key previous.key;

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

openssl rand 80 > ticket.key

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

ssl_session_tickets on;

Разрешает или запрещает возобновление сессий при помощи TLS session tickets.

ssl_session_timeout 5m;

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

ssl_stapling off;

Разрешает или запрещает прикрепление OCSP-ответов сервером. Пример:

ssl_stapling on;
resolver 192.0.2.1;

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

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

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

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

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

Поддерживаются только “http://” OCSP responder’ы:

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

ssl_stapling_verify off;

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

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

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

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

ssl_verify_client off;

Разрешает проверку клиентских сертификатов. Результат проверки доступен через переменную $ssl_client_verify. Если при проверке клиентского сертификата произошла ошибка или клиент не предоставил требуемый сертификат, соединение закрывается.

Параметр optional запрашивает клиентский сертификат, и если сертификат был предоставлен, проверяет его.

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

ssl_verify_depth 1;

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

Модуль ngx_stream_ssl_module поддерживает переменные начиная с версии 1.11.2.

$ssl_alpn_protocol

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

$ssl_cipher

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

$ssl_ciphers

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

AES128-SHA:AES256-SHA:0x00ff

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

$ssl_client_cert

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

$ssl_client_fingerprint

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

$ssl_client_i_dn

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

$ssl_client_raw_cert

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

$ssl_client_s_dn

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

$ssl_client_serial

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

$ssl_client_v_end

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

$ssl_client_v_remain

возвращает число дней, оставшихся до истечения срока действия клиентского сертификата (1.11.8);

$ssl_client_v_start

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

$ssl_client_verify

возвращает результат проверки клиентского сертификата (1.11.8): “SUCCESS”, “FAILED:reason” и, если сертификат не был предоставлен, “NONE”;

$ssl_curve

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

prime256v1

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

$ssl_curves

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

0x001d:prime256v1:secp521r1:secp384r1

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

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

$ssl_protocol

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

$ssl_server_name

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

$ssl_session_id

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

$ssl_session_reused

возвращает “r”, если сессия была использована повторно, иначе “.”.