Модуль ngx_stream_ssl_module

• Пример конфигурации
• Директивы
• ssl_alpn
• ssl_certificate
• ssl_certificate_cache
• ssl_certificate_compression
• ssl_certificate_key
• ssl_ciphers
• ssl_client_certificate
• ssl_conf_command
• ssl_crl
• ssl_dhparam
• ssl_ecdh_curve
• ssl_ech_file
• ssl_handshake_timeout
• ssl_key_log
• 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_stream_ssl_module (1.9.0) предоставляет необходимую поддержку для работы потокового прокси-сервера с протоколом SSL/TLS.

Этот модуль не собирается по умолчанию; для его включения следует использовать параметр конфигурации --with-stream_ssl_module.

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

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

Чтобы снизить нагрузку на процессор, рекомендуется

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

worker_processes auto;

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

Задаёт file с сертификатом в формате 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 или выше в имени file можно использовать переменные:

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

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

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

Следует иметь в виду, что из-за ограничений протокола SSL/TLS для обеспечения максимальной совместимости с клиентами, не использующими SNI, виртуальные серверы с разными сертификатами должны прослушивать разные IP-адреса.

Определяет кэш для хранения SSL-сертификатов и секретных ключей, заданных с помощью переменных.

Директива имеет следующие параметры:

max

задаёт максимальное количество элементов в кэше; при переполнении удаляются наименее недавно использовавшиеся (LRU) элементы;

inactive

задаёт время, по истечении которого элемент удаляется из кэша, если за это время к нему не обращались; по умолчанию — 10 секунд;

valid

задаёт время, в течение которого элемент кэша считается действительным и может быть использован повторно; по умолчанию — 60 секунд. Сертификаты, срок действия которых истёк, будут загружены повторно или проверены заново;

off

отключает кэш.

Пример:

ssl_certificate       $ssl_server_name.crt;
ssl_certificate_key   $ssl_server_name.key;
ssl_certificate_cache max=1000 inactive=20s valid=1m;

Включает сжатие сертификатов сервера в TLS 1.3.

Директива поддерживается при использовании OpenSSL версии 3.2 или выше; список поддерживаемых алгоритмов сжатия предоставляет библиотека.

Директива поддерживается при использовании BoringSSL; список поддерживаемых алгоритмов сжатия включает zlib (1.29.3).

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

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

Вместо file можно указать значение store:scheme:id (1.29.0), которое используется для загрузки секретного ключа с указанным id и URI scheme, зарегистрированным в провайдере OpenSSL, например pkcs11.

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

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

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

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

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

Задаёт 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 по умолчанию использовались встроенные параметры.

Задаёт 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 важно включить кривые, используемые в сертификатах.

Задаёт file с конфигурацией зашифрованного ClientHello (ECHConfig) в формате PEM, используемый для включения TLS 1.3 ECH в общем режиме.

В настоящее время директива поддерживается только при использовании ветки OpenSSL с поддержкой ECH.

Задаёт время ожидания завершения SSL-рукопожатия.

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

Эта директива доступна в рамках нашей коммерческой подписки.

Включает проверку цепочки сертификатов клиента с помощью 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-респондера, заданный в расширении сертификата «Доступ к информации об издателе», для проверки сертификатов клиентов.

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

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

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

Пример:

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

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

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

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

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

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

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

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

Например, в следующей конфигурации отклоняются 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 session ticket (1.23.2), если они явно не настроены с помощью директивы ssl_session_ticket_key.

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

ssl_session_cache builtin:1000 shared:SSL:10m;

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

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

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

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 байт).

Включает или отключает возобновление сеанса с помощью TLS session ticket.

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

Включает или отключает передачу сервером ответов OCSP в режиме stapling. Пример:

ssl_stapling on;
resolver 192.0.2.1;

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

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

Если параметр задан, ответ OCSP для stapling будет взят из указанного file вместо отправки запроса OCSP-респондеру, указанному в сертификате сервера.

Файл должен быть в формате DER, полученном с помощью команды «openssl ocsp».

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

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

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

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

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

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

В отличие от сертификатов, заданных директивой ssl_client_certificate, список этих сертификатов не отправляется клиентам.

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

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

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

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

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

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

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

возвращает сертификат клиента в формате PEM для установленного SSL-соединения; перед каждой строкой, кроме первой, добавляется символ табуляции (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

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

$ssl_client_s_dn

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

$ssl_client_serial

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

$ssl_client_sigalg

возвращает алгоритм подписи сертификата клиента для установленного SSL-соединения (1.29.3).

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

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

$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 (1.21.5). Известные кривые перечислены по именам, неизвестные отображаются в шестнадцатеричном формате, например:

prime256v1

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

$ssl_curves

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

0x001d:prime256v1:secp521r1:secp384r1

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

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

$ssl_ech_outer_server_name

возвращает общедоступное имя сервера, запрошенное через SNI, если TLS 1.3 ECH был принят, в противном случае — «» (1.29.4);

$ssl_ech_status

возвращает результат обработки TLS 1.3 ECH: «FAILED», «BACKEND», «GREASE», «SUCCESS» или «NOT_TRIED» (1.29.4);

В настоящее время переменная поддерживается только при использовании ветки OpenSSL с поддержкой ECH, поэтому её поведение может измениться. В противном случае значением переменной будет пустая строка.

$ssl_protocol

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

$ssl_server_name

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

$ssl_session_id

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

$ssl_session_reused

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

$ssl_sigalg

возвращает алгоритм подписи сертификата сервера для установленного SSL-соединения (1.29.3).

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

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