SSL#

Обеспечивает работу по протоколу HTTPS.

Примечание

Для этого модуля нужна библиотека 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/angie/conf/cert.pem;
        ssl_certificate_key /usr/local/angie/conf/cert.key;
        ssl_session_cache   shared:SSL:10m;
        ssl_session_timeout 10m;

        # ...
    }

Директивы#

ssl_buffer_size#

Синтаксис	`ssl_buffer_size` размер;
По умолчанию	`ssl_buffer_size 16k;`
Контекст	http, server

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

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

ssl_buffer_size 4k;

ssl_certificate#

Синтаксис	`ssl_certificate` файл \| `data:`сертификат;
По умолчанию	—
Контекст	http, server

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

Значение задает путь к файлу сертификата; относительный путь отсчитывается от каталога основного файла конфигурации. Значение, которое начинается с data:, содержит сам сертификат в виде текста PEM, и файл не нужен. Такое значение заключают в кавычки, поскольку текст PEM содержит пробелы. Чтобы записать его одной строкой в конфигурации с отступами, каждый перевод строки указывают как \n:

ssl_certificate 'data:-----BEGIN CERTIFICATE-----\nMIIBszCCAVmgAwIBAgIU...\n-----END CERTIFICATE-----\n';

Перевод строки можно записать и как есть, но тогда каждая следующая строка текста PEM должна начинаться с первой позиции; с отступами сертификат не загрузится:

ssl_certificate     'data:-----BEGIN CERTIFICATE-----
MIIBszCCAVmgAwIBAgIU...
-----END CERTIFICATE-----';
ssl_certificate_key /etc/angie/ssl/example.com.key;

Эта директива может быть указана несколько раз для загрузки сертификатов разных типов, например 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;

    # ...
}

Значение может целиком или частично состоять из переменных. Если хотя бы одно значение ssl_certificate или ssl_certificate_key виртуального сервера содержит переменные, Angie загружает все сертификаты и ключи этого сервера при каждом SSL-рукопожатии, а не при чтении конфигурации. Вычисленное значение интерпретируется так же, как описано выше: как текст PEM, если оно начинается с data:, и как путь к файлу в остальных случаях:

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

Рукопожатие происходит до запроса, поэтому значения есть только у переменных, известных к этому моменту: например, у $ssl_server_name, $remote_addr, $server_addr и у переменных, которые map вычисляет на их основе. Переменная, которой значение присваивает set, во время рукопожатия еще пуста, а с пустым значением рукопожатие завершается ошибкой. Готовое значение вида data: содержит, например, переменная $acme_cert_<name> модуля ACME.

Загрузка сертификатов при каждом рукопожатии расходует процессорное время; директива ssl_certificate_cache сохраняет загруженные сертификаты и ключи для повторного использования. Сертификаты, загруженные во время рукопожатия, не сжимаются, и к ним не прикрепляются OCSP-ответы: ssl_stapling и ssl_certificate_compression на них не действуют.

Примечание

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

Если задан режим ssl_ntls, директива может принимать два аргумента (части сертификата для подписи и шифрования) вместо одного:

listen ... ssl;

ssl_ntls  on;

# двойной сертификат NTLS
ssl_certificate      sign.crt enc.crt;
ssl_certificate_key  sign.key enc.key;

# можно использовать наряду с обычным сертификатом RSA
ssl_certificate  rsa.crt;
ssl_certificate_key rsa.key;

ssl_certificate_cache#

Синтаксис

ssl_certificate_cache off;

ssl_certificate_cache max=N [inactive=time] [valid=time];

Значение по умолчанию

ssl_certificate_cache off;

Контекст

http, server

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

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

max — устанавливает максимальное количество элементов в кэше. При переполнении кэша удаляются наименее недавно использованные (LRU) элементы.
inactive — определяет время, после которого элемент будет удален, если к нему не было обращений в течение этого времени, даже если он еще находится в пределах своего периода valid; каждое обращение сбрасывает этот таймер. Значение по умолчанию — 10 секунд.
valid — определяет время, в течение которого элемент кэша используется повторно без проверок. Значение по умолчанию — 60 секунд. По истечении этого времени элемент, загруженный из файла, перезагружается, только если файл изменился, а ключ, загруженный с префиксом engine: или store:, загружается заново; элемент, заданный с префиксом data:, остается действительным.
off — отключает кэш.

Ключи, защищенные паролем (см. ssl_password_file), не кэшируются.

Пример:

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

ssl_certificate_compression#

Синтаксис	`ssl_certificate_compression` `on` \| `off`;
Значение по умолчанию	`ssl_certificate_compression off;`
Контекст	http, server

Разрешает сжатие TLS 1.3 сертификатов сервера.

Примечание

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

Примечание

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

Директива несовместима с ssl_stapling: конфигурация, в которой обе директивы включены в одном сервере, не загружается.

ssl_certificate_key#

Синтаксис	`ssl_certificate_key` файл \| `data:`ключ \| `engine:`имя`:`id \| `store:`uri;
По умолчанию	—
Контекст	http, server

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

Путь к файлу и значение data: интерпретируются так же, как в ssl_certificate. Только для ключей доступны еще два префикса:

engine:имя:id — ключ с идентификатором id из движка OpenSSL имя;
store:uri — ключ, который OpenSSL STORE API находит по адресу uri, например ключ на токене, заданный URI PKCS #11, вида 'store:pkcs11:token=hsm;object=server'; из-за символа ; такое значение заключают в кавычки.

Значение может содержать переменные; тогда Angie загружает ключ вместе с сертификатом при каждом SSL-рукопожатии, как описано в ssl_certificate. Ключ, защищенный паролем, расшифровывается паролями из ssl_password_file независимо от того, загружается он вместе с конфигурацией или во время рукопожатия.

Значение может целиком попасть в лог ошибок: его приводит сообщение о ключе, который не удалось загрузить, а при использовании переменных отладочный лог записывает каждое вычисленное значение сертификата и ключа при каждом рукопожатии. Таким образом, с префиксом data: в лог попадает сам секретный ключ.

Если задан режим ssl_ntls, директива может принимать два аргумента (части ключа для подписи и шифрования) вместо одного:

listen ... ssl;

ssl_ntls  on;

# двойной сертификат NTLS
ssl_certificate      sign.crt enc.crt;
ssl_certificate_key  sign.key enc.key;

# можно использовать наряду с обычным сертификатом RSA
ssl_certificate  rsa.crt;
ssl_certificate_key rsa.key;

ssl_ciphers#

Синтаксис	`ssl_ciphers` шифры;
По умолчанию	`ssl_ciphers HIGH:!aNULL:!MD5;`
Контекст	http, server

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

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

Список шифров зависит от установленной версии OpenSSL. Полный список можно посмотреть с помощью команды openssl ciphers.

Предупреждение

При использовании OpenSSL директива ssl_ciphers не настраивает шифры TLS 1.3: их задает команда Ciphersuites директивы ssl_conf_command. Имена шифров TLS 1.3 в значении директивы ssl_ciphers игнорируются и не ограничивают соединения TLS 1.3. Если значение состоит только из таких имен, например TLS_AES_128_GCM_SHA256, загрузка конфигурации завершается ошибкой no cipher match.

В LibreSSL шифры TLS 1.3 можно настраивать с помощью ssl_ciphers.
В BoringSSL шифры TLS 1.3 настроить невозможно.

ssl_client_certificate#

Синтаксис	`ssl_client_certificate` файл;
По умолчанию	—
Контекст	http, server

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

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

ssl_conf_command#

Синтаксис	`ssl_conf_command` имя значение;
По умолчанию	—
Контекст	http, server

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

Примечание

Директива поддерживается при использовании OpenSSL 1.0.2 и выше. Шифры TLS 1.3 настраиваются командой Ciphersuites, доступной в OpenSSL 1.1.1 и выше.

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

ssl_conf_command Options PrioritizeChaCha;
ssl_conf_command Ciphersuites TLS_CHACHA20_POLY1305_SHA256;

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

Предупреждение

Изменение настроек OpenSSL напрямую может привести к неожиданному поведению.

ssl_crl#

Синтаксис	`ssl_crl` файл;
По умолчанию	—
Контекст	http, server

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

ssl_dhparam#

Синтаксис	`ssl_dhparam` файл;
По умолчанию	—
Контекст	http, server

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

Предупреждение

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

ssl_early_data#

Синтаксис	`ssl_early_data` `on` \| `off`;
По умолчанию	`ssl_early_data off;`
Контекст	http, server

Разрешает или запрещает TLS 1.3 early data.

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

proxy_set_header Early-Data $ssl_early_data;

Примечание

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

ssl_ecdh_curve#

Синтаксис	`ssl_ecdh_curve` кривая;
По умолчанию	`ssl_ecdh_curve auto;`
Контекст	http, server

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

Примечание

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

ssl_ecdh_curve prime256v1:secp384r1;

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

Примечание

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

ssl_encrypted_hello_key#

Синтаксис	`ssl_encrypted_hello_key` файл;
По умолчанию	—
Контекст	http, server

Указывает файл с секретным ключом и конфигурацией расширения TLS Encrypted Client Hello (ECH), которое скрывает имя сервера, запрашиваемое клиентом, от наблюдателей в сети. Переменная $ssl_encrypted_hello показывает, использовалось ли расширение при рукопожатии.

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

ssl_encrypted_hello_key current.ech;
ssl_encrypted_hello_key previous.ech;

Файл содержит секретный ключ, за которым следует ECHConfigList; оба в формате PEM. В ветке OpenSSL с поддержкой ECH такой файл создается командой:

$ openssl ech -public_name public.example.com -out example.ech

В BoringSSL команда bssl generate-ech записывает ключ и ECHConfigList в отдельные двоичные файлы, и напрямую использовать их нельзя. Из них нужно собрать один файл PEM: необработанный ключ обернуть в структуру PKCS#8 и закодировать в base64 в виде блока PRIVATE KEY, а следом поместить ECHConfigList, а не отдельный ECHConfig, закодированный в base64, в виде блока ECHCONFIG. Сборки с BoringSSL поддерживают только ключи X25519. Сам формат не зависит от библиотеки TLS, поэтому файл, созданный приведенной выше командой, подходит и для сборки с BoringSSL.

Angie расшифровывает ClientHello до того, как узнает имя сервера, запрошенное через SNI, поэтому ключи необходимо указывать для сервера по умолчанию.

Примечание

Поддержка ECH обеспечивается библиотекой TLS, поэтому Angie необходимо собрать с библиотекой, которая ее реализует: с веткой OpenSSL с поддержкой ECH, которая подключается так:

$ ./configure --with-openssl=../openssl-ech

либо с BoringSSL, который подключается иначе. В противном случае директива игнорируется с предупреждением в журнале ошибок.

ssl_keylog_file#

Синтаксис	`ssl_keylog_file` файл;
По умолчанию	—
Контекст	http, server

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

Директиву не следует использовать с LibreSSL.

Предупреждение

Файл содержит конфиденциальный ключевой материал TLS, с помощью которого можно расшифровать перехваченный трафик соответствующих соединений. Используйте директиву только для отладки или анализа протокола, ограничьте доступ к файлу и удалите его, когда он больше не нужен.

ssl_ntls#

Синтаксис	`ssl_ntls` `on` \| `off`;
По умолчанию	`ssl_ntls off;`
Контекст	http, server

Включает серверную поддержку NTLS при использовании TLS библиотеки Tongsuo

listen ... ssl;
ssl_ntls  on;

ssl_ocsp#

Синтаксис	`ssl_ocsp` `on` \| `off` \| `leaf`;
По умолчанию	`ssl_ocsp off;`
Контекст	http, server

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

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

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

Пример:

ssl_verify_client on;
ssl_ocsp          on;
resolver          127.0.0.53;

ssl_ocsp_cache#

Синтаксис	`ssl_ocsp_cache` `off` \| [`shared:`имя:размер];
По умолчанию	`ssl_ocsp_cache off;`
Контекст	http, server

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

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

ssl_ocsp_responder#

Синтаксис	`ssl_ocsp_responder` uri;
По умолчанию	—
Контекст	http, server

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

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

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

ssl_password_file#

Синтаксис	`ssl_password_file` файл;
По умолчанию	—
Контекст	http, server

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

Пример:

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;

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

ssl_prefer_server_ciphers#

Синтаксис	`ssl_prefer_server_ciphers` `on` \| `off`;
По умолчанию	`ssl_prefer_server_ciphers off;`
Контекст	http, server

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

ssl_protocols#

Синтаксис	`ssl_protocols` `SSLv2` \| `SSLv3` \| `TLSv1` \| `TLSv1.1` \| `TLSv1.2` \| `TLSv1.3` ...;
По умолчанию	`ssl_protocols TLSv1.2 TLSv1.3;`
Контекст	http, server

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

Примечание

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

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

ssl_reject_handshake#

Синтаксис	`ssl_reject_handshake` `on` \| `off`;
По умолчанию	`ssl_reject_handshake off;`
Контекст	http, server

Если включено, то операции 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;
}

ssl_session_cache#

Синтаксис	`ssl_session_cache` `off` \| `none` \| [`builtin`[:размер]] [`shared:`название:размер];
По умолчанию	`ssl_session_cache none;`
Контекст	http, server

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

`off`	жесткое запрещение использования кэша сессий: Angie явно сообщает клиенту, что сессии не могут использоваться повторно.
`none`	мягкое запрещение использования кэша сессий: Angie сообщает клиенту, что сессии могут использоваться повторно, но на самом деле не хранит параметры сессии в кэше.
`builtin`	встроенный в OpenSSL кэш, используется в рамках только одного рабочего процесса. Размер кэша задается в сессиях. Если размер не задан, то он равен 20480 сессиям. Использование встроенного кэша может вести к фрагментации памяти.
`shared`	кэш, разделяемый между всеми рабочими процессами. Размер кэша задается в байтах, в 1 мегабайт может поместиться около 4000 сессий. У каждого разделяемого кэша должно быть произвольное название. Кэш с одинаковым названием может использоваться в нескольких виртуальных серверах. Также он используется для автоматического создания, хранения и периодического обновления ключей сессионных билетов TLS, если они не указаны явно с помощью директивы ssl_session_ticket_key.

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

ssl_session_cache builtin:1000 shared:SSL:10m;

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

ssl_session_ticket_key#

Синтаксис	`ssl_session_ticket_key` файл;
По умолчанию	—
Контекст	http, server

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

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

ssl_session_ticket_key current.key;
ssl_session_ticket_key previous.key;

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

$ openssl rand 80 > ticket.key

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

ssl_session_tickets#

Синтаксис	`ssl_session_tickets` `on` \| `off`;
По умолчанию	`ssl_session_tickets on;`
Контекст	http, server

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

ssl_session_timeout#

Синтаксис	`ssl_session_timeout` время;
По умолчанию	`ssl_session_timeout 5m;`
Контекст	http, server

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

ssl_stapling#

Синтаксис	`ssl_stapling` `on` \| `off`;
По умолчанию	`ssl_stapling off;`
Контекст	http, server

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

ssl_stapling on;
resolver 127.0.0.53;

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

Предупреждение

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

ssl_stapling_file#

Синтаксис	`ssl_stapling_file` файл;
По умолчанию	—
Контекст	http, server

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

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

ssl_stapling_responder#

Синтаксис	`ssl_stapling_responder` url;
По умолчанию	—
Контекст	http, server

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

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

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

ssl_stapling_verify#

Синтаксис	`ssl_stapling_verify` `on` \| `off`;
По умолчанию	`ssl_stapling_verify off;`
Контекст	http, server

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

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

ssl_trusted_certificate#

Синтаксис	`ssl_trusted_certificate` файл;
По умолчанию	—
Контекст	http, server

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

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

ssl_verify_client#

Синтаксис	`ssl_verify_client` `on` \| `off` \| `optional` \| `optional_no_ca`;
По умолчанию	`ssl_verify_client off;`
Контекст	http, server

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

optional

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

optional_no_ca

запрашивает сертификат клиента, но не требует, чтобы он был подписан доверенным сертификатом CA. Это предназначено для случаев, когда фактическая проверка сертификата осуществляется внешним по отношению к Angie сервисом.

ssl_verify_depth#

Синтаксис	`ssl_verify_depth` число;
По умолчанию	`ssl_verify_depth 1;`
Контекст	http, server

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

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

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

`495`	при проверке клиентского сертификата произошла ошибка;
`496`	клиент не предоставил требуемый сертификат;
`497`	обычный запрос был послан на порт HTTPS.

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

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

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

`$ssl_alpn_protocol`#

возвращает протокол, выбранный при помощи ALPN во время SSL-рукопожатия, либо пустую строку.

`$ssl_cipher`#

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

`$ssl_ciphers`#

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

AES128-SHA:AES256-SHA:0x00ff

Примечание

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

`$ssl_client_escaped_cert`#

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

`$ssl_client_fingerprint`#

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

`$ssl_client_i_dn`#

возвращает строку "issuer DN" клиентского сертификата для установленного SSL-соединения согласно RFC 2253.

`$ssl_client_i_dn_legacy`#

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

`$ssl_client_raw_cert`#

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

`$ssl_client_s_dn`#

возвращает строку "subject DN" клиентского сертификата для установленного SSL-соединения согласно RFC 2253.

`$ssl_client_s_dn_legacy`#

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

`$ssl_client_serial`#

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

`$ssl_client_sigalg`#

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

Примечание

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

Примечание

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

`$ssl_client_v_end`#

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

`$ssl_client_v_remain`#

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

`$ssl_client_v_start`#

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

`$ssl_client_verify`#

возвращает результат проверки клиентского сертификата: SUCCESS, FAILED:reason и, если сертификат не был предоставлен, NONE.

`$ssl_curve`#

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

prime256v1

Примечание

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

`$ssl_curves`#

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

0x001d:prime256v1:secp521r1:secp384r1

Примечание

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

Примечание

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

`$ssl_early_data`#

возвращает 1, если используется TLS 1.3 early data и операция SSL-рукопожатия не завершена, иначе "".

`$ssl_encrypted_hello`#

возвращает 1, если ClientHello был расшифрован с помощью расширения TLS Encrypted Client Hello (ECH), иначе "".

`$ssl_protocol`#

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

`$ssl_server_cert_type`#

принимает значения RSA, DSA, ECDSA, ED448, ED25519, SM2, RSA-PSS или unknown в зависимости от типа сертификата и ключа сервера.

`$ssl_server_name`#

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

`$ssl_session_id`#

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

`$ssl_session_reused`#

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

`$ssl_sigalg`#

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

Примечание

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

Примечание

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

`$ssl_sigalgs`#

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

Примечание

При использовании OpenSSL версии 4.0 и выше алгоритмы возвращаются по именам; для алгоритма без имени используется соответствующий шестнадцатеричный код. SSL-библиотеки, предоставляющие прежний API алгоритмов подписи, возвращают все алгоритмы в виде шестнадцатеричных кодов. Если сборка не предоставляет поддерживаемого API алгоритмов подписи, значение переменной пустое.

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_encrypted_hello_key#

ssl_keylog_file#

ssl_ntls#

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#

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

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

$ssl_alpn_protocol#

$ssl_cipher#

$ssl_ciphers#

$ssl_client_escaped_cert#

$ssl_client_fingerprint#

$ssl_client_i_dn#

$ssl_client_i_dn_legacy#

$ssl_client_raw_cert#

$ssl_client_s_dn#

$ssl_client_s_dn_legacy#

$ssl_client_serial#

$ssl_client_sigalg#

$ssl_client_v_end#

$ssl_client_v_remain#

$ssl_client_v_start#

$ssl_client_verify#

$ssl_curve#

$ssl_curves#

$ssl_early_data#

$ssl_encrypted_hello#

$ssl_protocol#

$ssl_server_cert_type#

$ssl_server_name#

$ssl_session_id#

$ssl_session_reused#

$ssl_sigalg#

$ssl_sigalgs#

`$ssl_alpn_protocol`#

`$ssl_cipher`#

`$ssl_ciphers`#

`$ssl_client_escaped_cert`#

`$ssl_client_fingerprint`#

`$ssl_client_i_dn`#

`$ssl_client_i_dn_legacy`#

`$ssl_client_raw_cert`#

`$ssl_client_s_dn`#

`$ssl_client_s_dn_legacy`#

`$ssl_client_serial`#

`$ssl_client_sigalg`#

`$ssl_client_v_end`#

`$ssl_client_v_remain`#

`$ssl_client_v_start`#

`$ssl_client_verify`#

`$ssl_curve`#

`$ssl_curves`#

`$ssl_early_data`#

`$ssl_encrypted_hello`#

`$ssl_protocol`#

`$ssl_server_cert_type`#

`$ssl_server_name`#

`$ssl_session_id`#

`$ssl_session_reused`#

`$ssl_sigalg`#

`$ssl_sigalgs`#