Модуль ngx_mail_ssl_module

• Пример конфигурации
• Директивы
• ssl
• ssl_certificate
• ssl_certificate_compression
• 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.

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

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

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

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/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 можно указать значение data:certificate (1.15.10), которое загружает сертификат без использования промежуточных файлов. Обратите внимание, что ненадлежащее использование этого синтаксиса может повлечь угрозу безопасности, например привести к записи данных секретного ключа в журнал ошибок.

Включает сжатие сертификатов сервера в TLS 1.3.

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

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

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

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

Вместо file можно указать значение store:scheme:id (1.29.0), которое используется для загрузки секретного ключа с указанным id и URI, зарегистрированным в провайдере OpenSSL, scheme, например pkcs11.

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

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

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

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

В предыдущих версиях nginx по умолчанию использовались другие наборы шифров.

Указывает file с сертификатами доверенных центров сертификации в формате 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 session ticket (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-сеансов.

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

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

В отличие от сертификатов, заданных директивой ssl_client_certificate, список этих сертификатов не отправляется клиентам.

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

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

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

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

on

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

off

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

only

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