Модуль ngx_http_ssl_module обеспечивает работу
по протоколу HTTPS.
По умолчанию этот модуль не собирается, его сборку необходимо
разрешить с помощью конфигурационного параметра
--with-http_ssl_module .
Пример конфигурации
Для уменьшения загрузки процессора рекомендуется
-
установить число рабочих процессов равным числу процессоров,
-
разрешить keep-alive соединения,
-
включить разделяемый кэш сессий,
-
выключить встроенный кэш сессий
-
и, возможно, увеличить время жизни сессии (по умолчанию 5 минут):
worker_processes auto;
http {
...
server {
listen 443 ssl;
keepalive_timeout 70;
ssl_protocols SSLv3 TLSv1 TLSv1.1 TLSv1.2;
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;
...
}
Директивы
синтаксис:
|
ssl on | off ;
|
умолчание:
|
ssl off;
|
контекст:
|
http , server
|
Включает протокол HTTPS для данного виртуального сервера.
синтаксис:
|
ssl_buffer_size size ;
|
умолчание:
|
ssl_buffer_size 16k;
|
контекст:
|
http , server
|
Эта директива появилась в версии 1.5.9.
Задаёт размер буфера, используемого при отправке данных.
По умолчанию размер буфера равен 16k, что соответствует минимальным
накладным расходам при передаче больших ответов.
С целью минимизации времени получения начала ответа (Time To First Byte)
может быть полезно использовать меньшие значения,
например:
ssl_buffer_size 4k;
синтаксис:
|
ssl_certificate файл ;
|
умолчание:
|
—
|
контекст:
|
http , server
|
Указывает файл с сертификатом в формате PEM
для данного виртуального сервера.
Если вместе с основным сертификатом нужно указать промежуточные,
то они должны находиться в этом же файле в следующем порядке: сначала
основной сертификат, а затем промежуточные.
В этом же файле может находиться секретный ключ в формате PEM.
Нужно иметь в виду, что из-за ограничения протокола HTTPS
виртуальные серверы должны слушать на разных IP-адресах:
server {
listen 192.168.1.1:443;
server_name one.example.com;
ssl_certificate /usr/local/nginx/conf/one.example.com.cert;
...
}
server {
listen 192.168.1.2:443;
server_name two.example.com;
ssl_certificate /usr/local/nginx/conf/two.example.com.cert;
...
}
иначе для второго сайта будет выдаваться
сертификат первого сервера.
синтаксис:
|
ssl_certificate_key файл ;
|
умолчание:
|
—
|
контекст:
|
http , server
|
Указывает файл с секретным ключом в формате PEM
для данного виртуального сервера.
синтаксис:
|
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 файл ;
|
умолчание:
|
—
|
контекст:
|
http , server
|
Указывает файл с доверенными сертификатами CA в формате
PEM, которые используются для проверки клиентских сертификатов и
ответов OCSP, если включён ssl_stapling.
Список сертификатов будет отправляться клиентам.
Если это нежелательно, можно воспользоваться директивой
ssl_trusted_certificate.
синтаксис:
|
ssl_crl файл ;
|
умолчание:
|
—
|
контекст:
|
http , server
|
Эта директива появилась в версии 0.8.7.
Указывает файл с отозванными сертификатами (CRL)
в формате PEM, используемыми для проверки клиентских сертификатов.
синтаксис:
|
ssl_dhparam файл ;
|
умолчание:
|
—
|
контекст:
|
http , server
|
Эта директива появилась в версии 0.7.2.
Указывает файл с параметрами для шифров с обменом EDH-ключами.
синтаксис:
|
ssl_ecdh_curve кривая ;
|
умолчание:
|
ssl_ecdh_curve prime256v1;
|
контекст:
|
http , server
|
Эта директива появилась в версиях 1.1.0 и 1.0.6.
Задаёт кривую для ECDHE-шифров.
синтаксис:
|
ssl_prefer_server_ciphers on | off ;
|
умолчание:
|
ssl_prefer_server_ciphers off;
|
контекст:
|
http , server
|
Указывает, чтобы при использовании протоколов SSLv3 и TLS
серверные шифры были более приоритетны, чем клиентские.
синтаксис:
|
ssl_protocols
[SSLv2 ]
[SSLv3 ]
[TLSv1 ]
[TLSv1.1 ]
[TLSv1.2 ];
|
умолчание:
|
ssl_protocols SSLv3 TLSv1 TLSv1.1 TLSv1.2;
|
контекст:
|
http , server
|
Разрешает указанные протоколы.
Параметры TLSv1.1 и TLSv1.2 работают
только при использовании библиотеки OpenSSL версии 1.0.1 и выше.
синтаксис:
|
ssl_session_cache
off |
none |
[builtin [:размер ]]
[shared :название :размер ];
|
умолчание:
|
ssl_session_cache none;
|
контекст:
|
http , server
|
Задаёт тип и размеры кэшей для хранения параметров сессий.
Тип кэша может быть следующим:
off
-
жёсткое запрещение использования кэша сессий:
nginx явно говорит клиенту, что сессии не могут использоваться повторно.
none
-
мягкое запрещение использования кэша сессий:
nginx говорит клиенту, что сессии могут использоваться повторно, но
на самом деле не хранит параметры сессии в кэше.
builtin
-
встроенный в OpenSSL кэш, используется в рамках только одного рабочего процесса.
Размер кэша задаётся в сессиях.
Если размер не задан, то он равен 20480 сессиям.
Использование встроенного кэша может вести к фрагментации памяти.
shared
-
кэш, разделяемый между всеми рабочими процессами.
Размер кэша задаётся в байтах, в 1 мегабайт может поместиться
около 4000 сессий.
У каждого разделяемого кэша должно быть произвольное название.
Кэш с одинаковым названием может использоваться в нескольких
виртуальных серверах.
Можно использовать одновременно оба типа кэша, например:
ssl_session_cache builtin:1000 shared:SSL:10m;
однако использование только разделяемого кэша без встроенного должно
быть более эффективным.
синтаксис:
|
ssl_session_ticket_key файл ;
|
умолчание:
|
—
|
контекст:
|
http , server
|
Эта директива появилась в версии 1.5.7.
Задаёт файл с секретным ключом, применяемым при шифровании и
расшифровании TLS session tickets.
Директива необходима, если один и тот же ключ нужно использовать
на нескольких серверах.
По умолчанию используется случайно сгенерированный ключ.
Если указано несколько ключей, то только первый ключ
используется для шифрования TLS session tickets.
Это позволяет настроить ротацию ключей, например:
ssl_session_ticket_key current.key;
ssl_session_ticket_key previous.key;
Файл должен содержать 48 байт случайных данных и может быть
создан следующей командой:
openssl rand 48 > ticket.key
синтаксис:
|
ssl_session_tickets on | off ;
|
умолчание:
|
ssl_session_tickets on;
|
контекст:
|
http , server
|
Эта директива появилась в версии 1.5.9.
Разрешает или запрещает возобновление сессий при помощи
TLS session tickets.
синтаксис:
|
ssl_session_timeout время ;
|
умолчание:
|
ssl_session_timeout 5m;
|
контекст:
|
http , server
|
Задаёт время, в течение которого клиент может повторно
использовать параметры сессии, хранящейся в кэше.
синтаксис:
|
ssl_stapling on | off ;
|
умолчание:
|
ssl_stapling off;
|
контекст:
|
http , server
|
Эта директива появилась в версии 1.3.7.
Разрешает или запрещает
прикрепление
OCSP-ответов сервером.
Пример:
ssl_stapling on;
resolver 192.0.2.1;
Для работы OCSP stapling’а должен быть известен сертификат издателя
сертификата сервера.
Если в заданном директивой ssl_certificate
файле не содержится промежуточных сертификатов,
то сертификат издателя сертификата сервера следует поместить в файл,
заданный директивой ssl_trusted_certificate.
Для преобразования имени хоста OCSP responder’а в адрес необходимо
дополнительно задать директиву
resolver.
синтаксис:
|
ssl_stapling_file файл ;
|
умолчание:
|
—
|
контекст:
|
http , server
|
Эта директива появилась в версии 1.3.7.
Если задано, то вместо опроса OCSP responder’а,
указанного в сертификате сервера,
ответ берётся из указанного файла .
Ответ должен быть в формате DER и может быть сгенерирован командой
“openssl ocsp ”.
синтаксис:
|
ssl_stapling_responder url ;
|
умолчание:
|
—
|
контекст:
|
http , server
|
Эта директива появилась в версии 1.3.7.
Переопределяет URL OCSP responder’а, указанный в расширении сертификата
“Authority
Information Access”.
Поддерживаются только “http:// ” OCSP responder’ы:
ssl_stapling_responder http://ocsp.example.com/;
синтаксис:
|
ssl_stapling_verify on | off ;
|
умолчание:
|
ssl_stapling_verify off;
|
контекст:
|
http , server
|
Эта директива появилась в версии 1.3.7.
Разрешает или запрещает проверку сервером ответов OCSP.
Для работоспособности проверки сертификат издателя сертификата сервера,
корневой сертификат и все промежуточные сертификаты должны быть указаны
как доверенные с помощью директивы
ssl_trusted_certificate.
синтаксис:
|
ssl_trusted_certificate файл ;
|
умолчание:
|
—
|
контекст:
|
http , server
|
Эта директива появилась в версии 1.3.7.
Задаёт файл с доверенными сертификатами CA в формате PEM,
которые используются для проверки клиентских сертификатов и ответов OCSP,
если включён ssl_stapling.
В отличие от ssl_client_certificate, список этих сертификатов
не будет отправляться клиентам.
синтаксис:
|
ssl_verify_client
on | off |
optional | optional_no_ca ;
|
умолчание:
|
ssl_verify_client off;
|
контекст:
|
http , server
|
Разрешает проверку клиентских сертификатов.
Результат проверки доступен через переменную
$ssl_client_verify .
Параметр optional (0.8.7+) запрашивает клиентский
сертификат, и если сертификат был предоставлен, проверяет его.
Параметр optional_no_ca (1.3.8, 1.2.5)
запрашивает сертификат
клиента, но не требует, чтобы он был подписан доверенным сертификатом CA.
Это предназначено для случаев, когда фактическая проверка сертификата
осуществляется внешним по отношению к nginx’у сервисом.
Содержимое сертификата доступно через переменную
$ssl_client_cert .
синтаксис:
|
ssl_verify_depth число ;
|
умолчание:
|
ssl_verify_depth 1;
|
контекст:
|
http , server
|
Устанавливает глубину проверки в цепочке клиентских сертификатов.
Обработка ошибок
Модуль ngx_http_ssl_module поддерживает несколько
нестандартных кодов ошибок, которые можно использовать для
перенаправления с помощью директивы
error_page:
- 495
-
при проверке клиентского сертификата произошла ошибка;
- 496
-
клиент не предоставил требуемый сертификат;
- 497
-
обычный запрос был послан на порт HTTPS.
Перенаправление делается после того, как запрос полностью разобран
и доступны такие переменные, как $request_uri ,
$uri , $args и другие переменные.
Встроенные переменные
Модуль ngx_http_ssl_module поддерживает
несколько встроенных переменных:
$ssl_cipher
-
возвращает строку используемых шифров для установленного SSL-соединения;
$ssl_client_cert
-
возвращает клиентский сертификат
для установленного SSL-соединения в формате PEM
перед каждой строкой которого, кроме первой, вставляется символ табуляции;
предназначена для использования в директиве
proxy_set_header;
$ssl_client_raw_cert
-
возвращает клиентский сертификат
для установленного SSL-соединения в формате PEM;
$ssl_client_serial
-
возвращает серийный номер клиентского сертификата
для установленного SSL-соединения;
$ssl_client_s_dn
-
возвращает строку “subject DN” клиентского сертификата
для установленного SSL-соединения;
$ssl_client_i_dn
-
возвращает строку “issuer DN” клиентского сертификата
для установленного SSL-соединения;
$ssl_client_verify
-
возвращает результат проверки клиентского сертификата:
“
SUCCESS ”, “FAILED ” и,
если сертификат не был предоставлен — “NONE ”;
$ssl_protocol
-
возвращает протокол установленного SSL-соединения;
$ssl_server_name
-
возвращает имя сервера, запрошенное через
SNI
(1.7.0);
$ssl_session_id
-
возвращает идентификатор сессии установленного SSL-соединения;
$ssl_session_reused
-
возвращает “
r ”, если сессия была использована повторно,
иначе “. ” (1.5.11).
|