SSL#

Обеспечивает работу почтового прокси-сервера по протоколу SSL/TLS.

При сборке из исходного кода модуль не собирается по умолчанию; его необходимо включить с помощью параметра сборки ‑‑with‑mail_ssl_module. В пакетах и образах из наших репозиториев модуль включен в сборку.

Важно

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

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

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

worker_processes auto;

mail {

    ...

    server {
        listen              993 ssl;

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

Синтаксис

ssl_certificate файл;

По умолчанию

—

Контекст

mail, server

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

Директива может быть указана несколько раз для загрузки сертификатов разных типов, например RSA и ECDSA:

server {
    listen              993 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 и выше. Для более старых версий следует указывать только одну цепочку сертификатов.

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

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

ssl_certificate_key#

Синтаксис

ssl_certificate_key файл;

По умолчанию

—

Контекст

mail, server

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

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

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

ssl_ciphers#

Синтаксис

ssl_ciphers шифры;

По умолчанию

ssl_ciphers HIGH:!aNULL:!MD5;

Контекст

mail, server

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

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

Полный список можно посмотреть с помощью команды "openssl ciphers".

ssl_client_certificate#

Синтаксис

ssl_client_certificate файл;

По умолчанию

—

Контекст

mail, server

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

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

ssl_conf_command#

Синтаксис

ssl_conf_command имя значение;

По умолчанию

—

Контекст

mail, 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 файл;

По умолчанию

—

Контекст

mail, server

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

ssl_dhparam#

Синтаксис

ssl_dhparam файл;

По умолчанию

—

Контекст

mail, server

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

Осторожно

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

ssl_ecdh_curve#

Синтаксис

ssl_ecdh_curve кривая;

По умолчанию

ssl_ecdh_curve auto;

Контекст

mail, server

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

Важно

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

ssl_ecdh_curve prime256v1:secp384r1;

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

Важно

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

ssl_password_file#

Синтаксис

ssl_password_file файл;

По умолчанию

—

Контекст

mail, server

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

Пример:

mail {
    ssl_password_file /etc/keys/global.pass;
    ...

    server {
        server_name mail1.example.com;
        ssl_certificate_key /etc/keys/first.key;
    }

    server {
        server_name mail2.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;

Контекст

mail, server

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

ssl_protocols#

Синтаксис

ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];

По умолчанию

ssl_protocols TLSv1.2 TLSv1.3;

Контекст

mail, server

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

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

Важно

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

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

ssl_session_cache#

Синтаксис

ssl_session_cache off | none | [builtin[:размер]] [shared:название:размер];

По умолчанию

ssl_session_cache none;

Контекст

mail, 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 файл;

По умолчанию

—

Контекст

mail, 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;

Контекст

mail, server

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

ssl_session_timeout#

Синтаксис

ssl_session_timeout время;

По умолчанию

ssl_session_timeout 5m;

Контекст

mail, server

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

ssl_trusted_certificate#

Синтаксис

ssl_trusted_certificate файл;

По умолчанию

—

Контекст

mail, server

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

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

ssl_verify_client#

Синтаксис

ssl_verify_client on | off | optional | optional_no_ca;

По умолчанию

ssl_verify_client off;

Контекст

mail, server

Разрешает проверку клиентских сертификатов. Результат проверки передается в заголовке "Auth-SSL-Verify" в запросе аутентификации. Если при проверке клиентского сертификата произошла ошибка или клиент не предоставил требуемый сертификат, соединение закрывается.

optional

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

optional_no_ca

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

ssl_verify_depth#

Синтаксис

ssl_verify_depth число;

По умолчанию

ssl_verify_depth 1;

Контекст

mail, server

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

starttls#

Синтаксис

starttls on | off | only;

По умолчанию

starttls off;

Контекст

mail, server

on

разрешить использование команд STLS для POP3 и STARTTLS для IMAP и SMTP;

off

запретить использование команд STLS и STARTTLS;

only

требовать предварительного перехода на TLS.