Модуль http_ssl

Содержание

Модуль `http_ssl`#

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

По умолчанию этот модуль не собирается; его сборку необходимо включить с помощью параметра конфигурации ‑‑with‑http_ssl_module.

В пакетах из наших репозиториев модуль уже включен в сборку.

Важно

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

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

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

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

worker_processes auto;

http {

    # ...

    server {
        listen              443 ssl;
        keepalive_timeout   70;

        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/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 файл;
Умолчание:: —
Контекст:: http, server

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

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

Важно

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

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

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

Вместо файла можно указать значение «data:$переменная», при котором сертификат загружается из переменной без использования промежуточных файлов.

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

Важно

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

ssl_certificate_key#

Синтаксис:: ssl_certificate_key файл;
Умолчание:: —
Контекст:: http, server

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

Важно

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

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

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

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 ciphers».

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 и выше.

На одном уровне может быть указано несколько директив 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_ntls#

Добавлено в версии 1.2.0.

Синтаксис:: ssl_ntls on | off;
Умолчание:: ssl_ntls off;
Контекст:: http, server

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

listen ... ssl;
ssl_ntls  on;

Важно

Angie необходимо собрать с использованием параметра конфигурации –with-ntls, с соответствующей SSL библиотекой с поддержкой NTLS

./configure --with-openssl=../Tongsuo-8.3.0 \
            --with-openssl-opt=enable-ntls  \
            --with-ntls

ssl_ocsp#

Синтаксис:: ssl_ocsp on | off | leaf;
Умолчание:: ssl_ocsp off;
Контекст:: http, server

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

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

Для преобразования имени хоста OCSP responder’а в адрес необходимо дополнительно задать директиву 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 url;
Умолчание:: —
Контекст:: http, server

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

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

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 TLSv1.1 TLSv1.2 TLSv1.3;
Контекст:: http, server

Изменено в версии 1.2.0: Параметр TLSv1.3 добавлен к используемым по умолчанию.

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

Важно

Параметры 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 session tickets, если они не указаны явно с помощью директивы ssl_session_ticket_key.

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

ssl_session_cache builtin:1000 shared:SSL:10m;

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

ssl_session_ticket_key#

Синтаксис:: ssl_session_ticket_key файл;
Умолчание:: —
Контекст:: http, server

Задает файл с секретным ключом, применяемым при шифровании и расшифровании 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-байтных ключей), либо AES128 (для 48-байтных ключей).

ssl_session_tickets#

Синтаксис:: ssl_session_tickets on | off;
Умолчание:: ssl_session_tickets on;
Контекст:: http, server

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

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

Внимание

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

ssl_stapling_file#

Синтаксис:: ssl_stapling_file файл;
Умолчание:: —
Контекст:: http, server

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

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

ssl_stapling_responder#

Синтаксис:: ssl_stapling_responder url;
Умолчание:: —
Контекст:: http, server

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

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

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_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_protocol`#

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

`$ssl_server_name`#

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

`$ssl_session_id`#

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

`$ssl_session_reused`#

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

Модуль http_ssl

Содержание

Модуль http_ssl#

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

Директивы#

ssl_buffer_size#

ssl_certificate#

ssl_certificate_key#

ssl_ciphers#

ssl_client_certificate#

ssl_conf_command#

ssl_crl#

ssl_dhparam#

ssl_early_data#

ssl_ecdh_curve#

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

$ssl_client_v_remain#

$ssl_client_v_start#

$ssl_client_verify#

$ssl_curve#

$ssl_curves#

$ssl_early_data#

$ssl_protocol#

$ssl_server_name#

$ssl_session_id#

$ssl_session_reused#

Модуль `http_ssl`#

`$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_v_end`#

`$ssl_client_v_remain`#

`$ssl_client_v_start`#

`$ssl_client_verify`#

`$ssl_curve`#

`$ssl_curves`#

`$ssl_early_data`#

`$ssl_protocol`#

`$ssl_server_name`#

`$ssl_session_id`#

`$ssl_session_reused`#