SSL#

该模块为邮件代理协议（POP3、IMAP、SMTP）启用 SSL/TLS 加密支持，允许客户端和服务器之间进行安全通信。它为传入连接提供 SSL/TLS 加密，支持 STARTTLS 升级，管理证书和密钥，并控制 SSL 设置，如密码和协议版本。

当从 源代码构建 时， 该模块默认不会构建； 应该使用 ‑‑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 file;

默认值

—

上下文

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:`certificate` 来代替 file，这会加载证书而不使用中间文件。

请注意，不当使用此语法可能会带来安全隐患，例如将密钥数据写入 错误日志。

ssl_certificate_key#

语法

ssl_certificate_key file;

默认值

—

上下文

mail, server

指定给定服务器的 PEM 格式密钥文件。

可以指定值 engine:`name`:id 来代替 file，这会从 OpenSSL 引擎 name 加载指定 id 的密钥。

可以指定值 data:`key` 来代替 file，这会加载密钥而不使用中间文件。请注意，不当使用此语法可能会带来安全隐患，例如将密钥数据写入 错误日志。

ssl_ciphers#

语法

ssl_ciphers ciphers;

默认值

ssl_ciphers HIGH:!aNULL:!MD5;

上下文

mail, server

指定启用的密码。密码以 OpenSSL 库理解的格式指定，例如：

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

密码列表取决于已安装的 OpenSSL 版本。可以使用 openssl ciphers 命令查看完整列表。

警告

当使用 OpenSSL 时，ssl_ciphers 指令*不会*配置 TLS 1.3 的加密套件。要配置 OpenSSL 的 TLS 1.3 加密套件，请使用 ssl_conf_command 指令，该指令是为支持高级 SSL 配置而添加的。

  • 在 LibreSSL 中，可以 使用 ssl_ciphers 配置 TLS 1.3 加密套件。

  • 在 BoringSSL 中，完全无法配置 TLS 1.3 加密套件。

ssl_client_certificate#

语法

ssl_client_certificate file;

默认值

—

上下文

mail, server

指定用于 验证 客户端证书的 PEM 格式受信任 CA 证书文件。

证书列表将发送给客户端。如果不希望这样，可以使用 ssl_trusted_certificate 指令。

ssl_conf_command#

语法

ssl_conf_command name value;

默认值

—

上下文

mail, server

设置任意 OpenSSL 配置 命令。

备注

该指令在使用 OpenSSL 1.0.2 或更高版本时受支持。 要配置 OpenSSL 的 TLS 1.3 加密套件，请使用 ciphersuites 命令。

可以在同一级别上指定多个 ssl_conf_command 指令：

ssl_conf_command Options PrioritizeChaCha;
ssl_conf_command Ciphersuites TLS_CHACHA20_POLY1305_SHA256;

这些指令仅在当前级别没有定义 ssl_conf_command 指令时，才会从前一个配置级别继承。

警告

请注意，直接配置 OpenSSL 可能会导致意外行为。

ssl_crl#

语法

ssl_crl file;

默认值

—

上下文

mail, server

指定用于 验证 客户端证书的 PEM 格式撤销证书（CRL）文件。

ssl_dhparam#

语法

ssl_dhparam file;

默认值

—

上下文

mail, server

指定 DHE 密码的 DH 参数文件。

警告

默认情况下未设置参数，因此不会使用 DHE 密码。

ssl_ecdh_curve#

语法

ssl_ecdh_curve curve;

默认值

ssl_ecdh_curve auto;

上下文

mail, server

指定 ECDHE 密码的曲线。

备注

当使用 OpenSSL 1.0.2 或更高版本时，可以指定多个曲线，例如：

ssl_ecdh_curve prime256v1:secp384r1;

特殊值 auto 指示 Angie 在使用 OpenSSL 1.0.2 或更高版本时使用 OpenSSL 库内置的曲线列表，或在较旧版本中使用 prime256v1。

备注

当使用 OpenSSL 1.0.2 或更高版本时，此指令设置服务器支持的曲线列表。因此，为了使 ECDSA 证书正常工作，包含证书中使用的曲线非常重要。

ssl_password_file#

语法

ssl_password_file 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[:size]] [shared:name:size];

默认值

ssl_session_cache none;

上下文

mail, server

设置存储会话参数的缓存的类型和大小。缓存可以是以下类型中的任何一种：

off

严格禁止使用会话缓存：Angie 明确告诉客户端会话不能重用。

none

温和地不允许使用会话缓存：Angie 告诉客户端会话可以重用，但实际上不在缓存中存储会话参数。

builtin

OpenSSL 内置的缓存；仅由一个工作进程使用。缓存大小以会话为单位。如果未给出大小，则等于 20480 个会话。使用内置缓存可能会导致内存碎片。

shared

在所有工作进程之间共享的缓存。缓存大小以字节为单位；一兆字节大约可以存储 4000 个会话。每个共享缓存应具有任意名称。具有相同名称的缓存可以在几个服务器中使用。它还用于自动生成、存储和定期轮换 TLS 会话票据密钥，除非明确使用 ssl_session_ticket_key 指令配置。

可以同时使用两种缓存类型，例如：

ssl_session_cache builtin:1000 shared:SSL:10m;

但仅使用共享缓存而不使用内置缓存应更有效。

ssl_session_ticket_key#

语法

ssl_session_ticket_key file;

默认值

—

上下文

mail, server

设置一个文件，其中包含用于加密和解密 TLS 会话票据的密钥。该指令在多个服务器之间需要共享相同密钥时是必要的。默认情况下，使用随机生成的密钥。

如果指定多个密钥，则仅使用第一个密钥来加密 TLS 会话票据。这允许配置密钥轮换，例如：

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 会话票据 的会话恢复。

ssl_session_timeout#

语法

ssl_session_timeout time;

默认值

ssl_session_timeout 5m;

上下文

mail, server

指定客户端可以重用会话参数的时间。

ssl_trusted_certificate#

语法

ssl_trusted_certificate file;

默认值

—

上下文

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 证书签名。这适用于外部服务执行实际证书验证的情况。证书的内容可以通过请求 发送 给认证服务器访问。

ssl_verify_depth#

语法

ssl_verify_depth number;

默认值

ssl_verify_depth 1;

上下文

mail, server

设置客户端证书链中的验证深度。

starttls#

语法

starttls on | off | only;

默认值

starttls off;

上下文

mail, server

on

允许使用 POP3 的 STLS 命令和 IMAP 和 SMTP 的 STARTTLS 命令；

off

拒绝使用 STLS 和 STARTTLS 命令；

only

要求进行预先的 TLS 转换。