# SSL 该模块为邮件代理协议(POP3、IMAP、SMTP)启用 SSL/TLS 加密支持,允许客户端和服务器之间进行安全通信。它为传入连接提供 SSL/TLS 加密,支持 STARTTLS 升级,管理证书和密钥,并控制 SSL 设置,如密码和协议版本。 当从 [源代码构建](https://cn.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild) 时, 该模块默认不会构建; 应该使用 `‑‑with‑mail_ssl_module` [构建选项](https://cn.angie.software//angie/docs/installation/sourcebuild.md#configure) 启用它。 在来自 [我们仓库](https://cn.angie.software//angie/docs/installation/index.md#install-packages) 的软件包和镜像中, 该模块已包含在构建中。 #### NOTE 此模块需要 OpenSSL 库。 ## 配置示例 为了减少处理器负载,建议 * 将 [工作进程数量](https://cn.angie.software//angie/docs/configuration/modules/core.md#worker-processes) 设置为与处理器数量相等, * 启用 [共享](#m-ssl-session-cache) 会话缓存, * 禁用 [内置](#m-ssl-session-cache) 会话缓存, * 并可能增加会话 [生命周期](#m-ssl-session-timeout) (默认为 5 分钟): ```nginx 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 | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_certificate` file; | |--------------------------------------------------------------------------------------|---------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server | 指定给定服务器的 PEM 格式证书文件。如果除了主证书外还需要指定中间证书,应按以下顺序在同一文件中指定:主证书在前,然后是中间证书。PEM 格式的密钥可以放在同一文件中。 此指令可以多次指定,以加载不同类型的证书,例如 RSA 和 ECDSA: ```nginx 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`,这会加载证书而不使用中间文件。 请注意,不当使用此语法可能会带来安全隐患,例如将密钥数据写入 [错误日志](https://cn.angie.software//angie/docs/configuration/modules/core.md#error-log)。 ### ssl_certificate_compression | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_certificate_compression` `on` | `off`; | |--------------------------------------------------------------------------------------|-----------------------------------------------| | 默认值 | `ssl_certificate_compression off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server | 启用 TLS 1.3 服务器证书 [压缩](https://datatracker.ietf.org/doc/html/rfc8879)。 #### NOTE 该指令在使用 OpenSSL 3.2 或更高版本时受支持;支持的压缩算法列表由库提供。 #### NOTE 该指令在使用 [BoringSSL](https://boringssl.googlesource.com/boringssl/) 时受支持;支持的压缩算法列表包括 `zlib`。 ### ssl_certificate_key | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_certificate_key` file; | |--------------------------------------------------------------------------------------|-------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server | 指定给定服务器的 PEM 格式密钥文件。 可以指定值 `engine:`name`:id` 来代替 `file`,这会从 OpenSSL 引擎 name 加载指定 id 的密钥。 可以指定值 `store:scheme:id` 来代替 `file`,用于加载具有指定 id 和 OpenSSL 提供程序注册 URI scheme 的密钥,例如 [pkcs11](https://datatracker.ietf.org/doc/html/rfc7512)。 可以指定值 `data:`key`` 来代替 `file`,这会加载密钥而不使用中间文件。请注意,不当使用此语法可能会带来安全隐患,例如将密钥数据写入 [错误日志](https://cn.angie.software//angie/docs/configuration/modules/core.md#error-log)。 ### ssl_ciphers | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_ciphers` ciphers; | |--------------------------------------------------------------------------------------|---------------------------------| | 默认值 | `ssl_ciphers HIGH:!aNULL:!MD5;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server | 指定启用的密码。密码以 OpenSSL 库理解的格式指定,例如: ```nginx ssl_ciphers ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP; ``` 密码列表取决于已安装的 OpenSSL 版本。可以使用 `openssl ciphers` 命令查看完整列表。 #### WARNING 当使用 OpenSSL 时,:samp:ssl_ciphers 指令\*不会\*配置 TLS 1.3 的密码。要使用 OpenSSL 调整 TLS 1.3 密码,请使用 [ssl_conf_command](#m-ssl-conf-command) 指令,该指令是为支持高级 SSL 配置而添加的。 - 在 LibreSSL 中,\*可以\* 使用 `ssl_ciphers` 配置 TLS 1.3 密码。 - 在 BoringSSL 中,完全无法配置 TLS 1.3 密码。 ### ssl_client_certificate | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_client_certificate` file; | |--------------------------------------------------------------------------------------|----------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server | 指定用于 [验证](#m-ssl-verify-client) 客户端证书的 PEM 格式受信任 CA 证书文件。 证书列表将发送给客户端。如果不希望这样,可以使用 [ssl_trusted_certificate](#m-ssl-trusted-certificate) 指令。 ### ssl_conf_command | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_conf_command` name value; | |--------------------------------------------------------------------------------------|----------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server | 设置任意 OpenSSL 配置 [命令](https://docs.openssl.org/master/man3/SSL_CONF_cmd/)。 #### NOTE 该指令在使用 OpenSSL 1.0.2 或更高版本时受支持。 要使用 OpenSSL 配置 TLS 1.3 密码,请使用 `ciphersuites` 命令。 可以在同一级别上指定多个 ssl_conf_command 指令: ```nginx ssl_conf_command Options PrioritizeChaCha; ssl_conf_command Ciphersuites TLS_CHACHA20_POLY1305_SHA256; ``` 这些指令仅在当前级别没有定义 ssl_conf_command 指令时,才会从前一个配置级别继承。 #### WARNING 请注意,直接配置 OpenSSL 可能会导致意外行为。 ### ssl_crl | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_crl` file; | |--------------------------------------------------------------------------------------|-------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server | 指定用于 [验证](#m-ssl-verify-client) 客户端证书的 PEM 格式撤销证书(CRL)文件。 ### ssl_dhparam | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_dhparam` file; | |--------------------------------------------------------------------------------------|-----------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server | 指定 DHE 密码的 DH 参数文件。 #### WARNING 默认情况下未设置参数,因此不会使用 DHE 密码。 ### ssl_ecdh_curve | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_ecdh_curve` curve; | |--------------------------------------------------------------------------------------|---------------------------| | 默认值 | `ssl_ecdh_curve auto;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server | 指定 ECDHE 密码的曲线。 #### NOTE 当使用 OpenSSL 1.0.2 或更高版本时,可以指定多个曲线,例如: ```nginx ssl_ecdh_curve prime256v1:secp384r1; ``` 特殊值 `auto` 指示 Angie 在使用 OpenSSL 1.0.2 或更高版本时使用 OpenSSL 库内置的列表,或在较旧版本中使用 prime256v1。 #### NOTE 当使用 OpenSSL 1.0.2 或更高版本时,此指令设置服务器支持的曲线列表。因此,为了使 ECDSA 证书正常工作,包含证书中使用的曲线非常重要。 ### ssl_password_file | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_password_file` file; | |--------------------------------------------------------------------------------------|-----------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server | 指定一个文件,其中包含 [密钥](#m-ssl-certificate-key) 的密码短语,每个密码短语单独一行。加载密钥时会依次尝试这些密码短语。 示例: ```nginx 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 | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_prefer_server_ciphers` `on` | `off`; | |--------------------------------------------------------------------------------------|---------------------------------------------| | 默认值 | `ssl_prefer_server_ciphers off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server | 指定在使用 SSLv3 和 TLS 协议时,服务器密码应优先于客户端密码。 ### ssl_protocols | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_protocols` [`SSLv2`] [`SSLv3`] [`TLSv1`] [`TLSv1.1`] [`TLSv1.2`] [`TLSv1.3`]; | |--------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------| | 默认值 | `ssl_protocols TLSv1.2 TLSv1.3;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server | #### Versionchanged 在 1.2.0 版本发生变更: 默认设置中添加了 `TLSv1.3` 参数。 启用指定的协议。 #### NOTE `TLSv1.1` 和 `TLSv1.2` 参数仅在使用 OpenSSL 1.0.1 或更高版本时有效。 `TLSv1.3` 参数仅在使用 OpenSSL 1.1.1 或更高版本时有效。 ### ssl_session_cache | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_session_cache` `off` | `none` | [builtin[:size]] [shared:name:size]; | |--------------------------------------------------------------------------------------|-----------------------------------------------------------------------------| | 默认值 | `ssl_session_cache none;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server | 设置存储会话参数的缓存类型和大小。缓存可以是以下任意类型: | `off` | 严格禁止使用会话缓存:Angie 明确告知客户端会话不可重用。 | |-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `none` | 温和地禁止使用会话缓存:Angie 告知客户端会话可以重用,但实际上不在缓存中存储会话参数。 | | `builtin` | OpenSSL 内置缓存;仅由一个工作进程使用。缓存大小以会话数指定。如果未指定大小,则等于 20480 个会话。使用内置缓存可能导致内存碎片。 | | `shared` | 在所有工作进程之间共享的缓存。缓存大小以字节指定;一兆字节可以存储约 4000 个会话。每个共享缓存应有一个任意名称。具有相同名称的缓存可以在多个服务器中使用。除非使用 [ssl_session_ticket_key](#m-ssl-session-ticket-key) 指令显式配置,否则它还用于自动生成、存储和定期轮换 TLS 会话票证密钥。 | 两种缓存类型可以同时使用,例如: ```nginx ssl_session_cache builtin:1000 shared:SSL:10m; ``` 但仅使用共享缓存而不使用内置缓存应该更高效。 ### ssl_session_ticket_key | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_session_ticket_key` file; | |--------------------------------------------------------------------------------------|----------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server | 设置包含用于加密和解密 TLS 会话票证的密钥的文件。如果需要在多个服务器之间共享相同的密钥,则此指令是必需的。默认情况下,使用随机生成的密钥。 如果指定了多个密钥,则仅使用第一个密钥来加密 TLS 会话票证。这允许配置密钥轮换,例如: ```nginx ssl_session_ticket_key current.key; ssl_session_ticket_key previous.key; ``` 该文件必须包含 80 或 48 字节的随机数据,可以使用以下命令创建: ```console openssl rand 80 > ticket.key ``` 根据文件大小,使用 AES256(用于 80 字节密钥)或 AES128(用于 48 字节密钥)进行加密。 ### ssl_session_tickets | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_session_tickets` `on` | `off`; | |--------------------------------------------------------------------------------------|---------------------------------------| | 默认值 | `ssl_session_tickets on;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server | 启用或禁用通过 [TLS 会话票证](https://datatracker.ietf.org/doc/html/rfc5077) 恢复会话。 ### ssl_session_timeout | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_session_timeout` time; | |--------------------------------------------------------------------------------------|-------------------------------| | 默认值 | `ssl_session_timeout 5m;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server | 指定客户端可以重用会话参数的时间。 ### ssl_trusted_certificate | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_trusted_certificate` file; | |--------------------------------------------------------------------------------------|-----------------------------------| | 默认值 | — | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server | 指定包含 PEM 格式的受信任 CA 证书的文件,用于 [验证](#m-ssl-verify-client) 客户端证书。 与 [ssl_client_certificate](#m-ssl-client-certificate) 设置的证书集不同,这些证书列表不会发送给客户端。 ### ssl_verify_client | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_verify_client` `on` | `off` | `optional` | `optional_no_ca`; | |--------------------------------------------------------------------------------------|---------------------------------------------------------------------| | 默认值 | `ssl_verify_client off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server | 启用客户端证书的验证。验证结果将通过 [认证](https://cn.angie.software//angie/docs/configuration/modules/mail/mail_auth_http.md#m-auth-http) 请求的 `Auth-SSL-Verify` 头传递。如果在客户端证书验证过程中发生错误,或者客户端未提供所需的证书,则连接将被关闭。 | `optional` | 请求客户端证书,并在证书存在时进行验证 | |------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `optional_no_ca` | 请求客户端证书,但不要求其由受信任的 CA 证书签名。这适用于由 Angie 外部的服务执行实际证书验证的情况。证书的内容可以通过 [发送](https://cn.angie.software//angie/docs/configuration/modules/mail/mail_auth_http.md#m-auth-http-pass-client-cert) 到认证服务器的请求访问。 | ### ssl_verify_depth | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `ssl_verify_depth` number; | |--------------------------------------------------------------------------------------|------------------------------| | 默认值 | `ssl_verify_depth 1;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server | 设置客户端证书链中的验证深度。 ### starttls | [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | `starttls` `on` | `off` | `only`; | |--------------------------------------------------------------------------------------|-------------------------------------| | 默认值 | `starttls off;` | | [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile) | mail, server | | `on` | 允许对 POP3 使用 STLS 命令,对 IMAP 和 SMTP 使用 STARTTLS 命令; | |--------|-----------------------------------------------------| | `off` | 拒绝使用 STLS 和 STARTTLS 命令; | | `only` | 要求预先进行 TLS 转换。 |