Модуль ngx_stream_ssl_module

• Пример конфигурации
• Директивы
• ssl_alpn
• ssl_certificate
• ssl_certificate_key
• ssl_ciphers
• ssl_client_certificate
• ssl_conf_command
• ssl_crl
• ssl_dhparam
• ssl_ecdh_curve
• ssl_handshake_timeout
• 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_trusted_certificate
• ssl_verify_client
• ssl_verify_depth
• Встроенные переменные

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

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

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

• установить количество рабочих процессов равным количеству процессоров,
• включить кэширование сессий shared,
• отключить кэширование сессий builtin,
• и возможно увеличить срок действия сессии lifetime (по умолчанию 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;
}

Указывает 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, в имени file можно использовать переменные при использовании OpenSSL 1.0.2 или выше:

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

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

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

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

Вместо file, можно указать значение 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”.

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

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

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

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

Указывает таймаут для завершения SSL-handshake.

Указывает 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.

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

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

Параметры TLSv1.1 и TLSv1.2 работают только при использовании 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;

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

Устанавливает 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-байтовых ключей).

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

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

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

В отличие от сертификата, установленного с помощью 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_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_protocol

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

$ssl_server_name

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

$ssl_session_id

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

$ssl_session_reused

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