Модуль ngx_http_ssl_module

• Пример конфигурации
• Директивы
• ssl
• ssl_buffer_size
• ssl_certificate
• ssl_certificate_cache
• ssl_certificate_compression
• ssl_certificate_key
• ssl_ciphers
• ssl_client_certificate
• ssl_conf_command
• ssl_crl
• ssl_dhparam
• ssl_early_data
• ssl_ecdh_curve
• ssl_ech_file
• 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_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.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.

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

По умолчанию размер буфера составляет 16k, что обеспечивает минимальные накладные расходы при отправке больших ответов. Чтобы сократить время до получения первого байта (Time To First Byte), может быть полезно использовать меньшие значения, например:

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, при использовании 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 (1.7.9), которое загружает секретный ключ с указанным 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».

В предыдущих версиях 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.

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

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

proxy_set_header Early-Data $ssl_early_data;

Встроенная защита OpenSSL от повторного воспроизведения отключена, поскольку она мешает возобновлению сеанса. При необходимости её можно снова включить.

ssl_conf_command Options AntiReplay;

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

Пример:

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 следует отдавать предпочтение шифрам сервера, а не шифрам клиента.

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

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

Параметры 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-рукопожатия в блоке 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 (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 байт).

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

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

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

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 (0.8.7+) запрашивает сертификат клиента и проверяет его, если сертификат предоставлен.

Параметр optional_no_ca (1.3.8, 1.2.5) запрашивает сертификат клиента, но не требует, чтобы он был подписан доверенным сертификатом CA. Это предназначено для случаев, когда фактическую проверку сертификата выполняет служба, внешняя по отношению к nginx. Содержимое сертификата доступно через переменную $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 (с URL-кодированием) для установленного 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

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

$ssl_client_i_dn_legacy

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

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

$ssl_client_raw_cert

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

$ssl_client_s_dn

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

$ssl_client_s_dn_legacy

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

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

$ssl_client_serial

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

$ssl_client_sigalg

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

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

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

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

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

$ssl_ech_status

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

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

$ssl_protocol

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

$ssl_server_name

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

$ssl_session_id

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

$ssl_session_reused

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

$ssl_sigalg

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

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

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