Модуль ngx_mail_ssl_module

• Пример конфигурации
• Директивы
• ssl
• ssl_certificate
• ssl_certificate_key
• ssl_ciphers
• ssl_client_certificate
• ssl_conf_command
• ssl_crl
• ssl_dhparam
• ssl_ecdh_curve
• ssl_password_file
• ssl_prefer_server_ciphers
• ssl_protocols
• ssl_session_cache
• ssl_session_ticket_key
• ssl_session_tickets
• ssl_session_timeout
• ssl_trusted_certificate
• ssl_verify_client
• ssl_verify_depth
• starttls

Модуль ngx_mail_ssl_module предоставляет необходимую поддержку для работы почтового прокси-сервера с протоколом SSL/TLS.

Этот модуль не включается по умолчанию, его необходимо включить с помощью параметра конфигурации --with-mail_ssl_module.

Этот модуль требует библиотеку OpenSSL.

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

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

• установить количество процессов обработки запросов равное количеству процессоров,
• включить кэш сессий shared,
• отключить кэш сессий builtin,
• и, возможно, увеличить время жизни сессий сессии (по умолчанию 5 минут):

worker_processes auto;

mail {

    ...

    server {
        listen              993 ssl;

        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/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.

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

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

Вместо file (1.15.10) можно указать значение data:certificate, что загружает сертификат без использования промежуточных файлов. Обратите внимание, что некорректное использование данного синтаксиса может иметь последствия для безопасности, например, запись данных секретного ключа в журнал ошибок.

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

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

Вместо file (1.15.10) можно указать значение data:key, что загружает закрытый ключ без использования промежуточных файлов. Некорректное использование данного синтаксиса может иметь последствия для безопасности, например, запись данных секретного ключа в журнал ошибок.

Указывает включенные шифры. Шифры указываются в формате, понятном библиотеке OpenSSL, например:

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

Полный список можно просмотреть, используя команду “openssl ciphers”.

Предыдущие версии nginx использовали разные шифры по умолчанию.

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

Список сертификатов будет отправлен клиентам. Если этого не требуется, можно использовать директиву 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 параметры по умолчанию были встроенными.

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

Пример:

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;

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

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

Параметры 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.

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

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-сеанса TLS session tickets.

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

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

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

Включает проверку сертификатов клиентов. Результат проверки передаётся в заголовке «Auth-SSL-Verify» запроса аутентификации.

optional параметр запрашивает сертификат клиента и проверяет его, если сертификат есть.

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

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

on

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

off

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

only

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