> For the complete documentation index, see [llms.txt](https://docshome.gitbook.io/nginx-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docshome.gitbook.io/nginx-docs/he-xin-gong-neng/mail/ngx_mail_ssl_module.md).

# ngx\_mail\_ssl\_module

* [示例配置](/nginx-docs/he-xin-gong-neng/mail/ngx_mail_ssl_module.md#example_configuration)
* [指令](/nginx-docs/he-xin-gong-neng/mail/ngx_mail_ssl_module.md#directives)
  * [ssl](/nginx-docs/he-xin-gong-neng/mail/ngx_mail_ssl_module.md#ssl)
  * [ssl\_certificate](/nginx-docs/he-xin-gong-neng/mail/ngx_mail_ssl_module.md#ssl_certificate)
  * [ssl\_certificate\_key](/nginx-docs/he-xin-gong-neng/mail/ngx_mail_ssl_module.md#ssl_certificate_key)
  * [ssl\_ciphers](/nginx-docs/he-xin-gong-neng/mail/ngx_mail_ssl_module.md#ssl_ciphers)
  * [ssl\_client\_certificate](/nginx-docs/he-xin-gong-neng/mail/ngx_mail_ssl_module.md#ssl_client_certificate)
  * [ssl\_crl](/nginx-docs/he-xin-gong-neng/mail/ngx_mail_ssl_module.md#ssl_crl)
  * [ssl\_dhparam](/nginx-docs/he-xin-gong-neng/mail/ngx_mail_ssl_module.md#ssl_dhparam)
  * [ssl\_ecdh\_curve](/nginx-docs/he-xin-gong-neng/mail/ngx_mail_ssl_module.md#ssl_ecdh_curve)
  * [ssl\_password\_file](/nginx-docs/he-xin-gong-neng/mail/ngx_mail_ssl_module.md#ssl_password_file)
  * [ssl\_prefer\_server\_ciphers](/nginx-docs/he-xin-gong-neng/mail/ngx_mail_ssl_module.md#ssl_prefer_server_ciphers)
  * [ssl\_protocols](/nginx-docs/he-xin-gong-neng/mail/ngx_mail_ssl_module.md#ssl_protocols)
  * [ssl\_session\_cache](/nginx-docs/he-xin-gong-neng/mail/ngx_mail_ssl_module.md#ssl_session_cache)
  * [ssl\_session\_ticket\_key](/nginx-docs/he-xin-gong-neng/mail/ngx_mail_ssl_module.md#ssl_session_ticket_key)
  * [ssl\_session\_tickets](/nginx-docs/he-xin-gong-neng/mail/ngx_mail_ssl_module.md#ssl_session_tickets)
  * [ssl\_session\_timeout](/nginx-docs/he-xin-gong-neng/mail/ngx_mail_ssl_module.md#ssl_session_timeout)
  * [ssl\_trusted\_certificate](/nginx-docs/he-xin-gong-neng/mail/ngx_mail_ssl_module.md#ssl_trusted_certificate)
  * [ssl\_verify\_client](/nginx-docs/he-xin-gong-neng/mail/ngx_mail_ssl_module.md#ssl_verify_client)
  * [ssl\_verify\_depth](/nginx-docs/he-xin-gong-neng/mail/ngx_mail_ssl_module.md#ssl_verify_depth)
  * [starttls](/nginx-docs/he-xin-gong-neng/mail/ngx_mail_ssl_module.md#starttls)

`ngx_mail_ssl_module` 模块可让邮件代理服务器支持 SSL/TLS 协议。

默认情况下不构建此模块，可在构建时使用 `--with-mail_ssl_module` 配置参数启用它。

> 该模块依赖 [OpenSSL](http://www.openssl.org/) 库。

## 示例配置 <a href="#example_configuration" id="example_configuration"></a>

为了减轻处理器负载，建议：

* 将 [worker 进程](/nginx-docs/he-xin-gong-neng.md#worker_processes)数设置为与处理器数量相等
* 启用[共享](/nginx-docs/he-xin-gong-neng/mail/ngx_mail_ssl_module.md#ssl_session_cache_shared)会话缓存
* 禁用[内置](/nginx-docs/he-xin-gong-neng/mail/ngx_mail_ssl_module.md#ssl_session_cache_builtin)的会话缓存
* 可以延长会话的[生命周期](/nginx-docs/he-xin-gong-neng/mail/ngx_mail_ssl_module.md#ssl_session_timeout)（默认为 5 分钟）

```
worker_processes auto;

mail {

    ...

    server {
        listen              993 ssl;

        ssl_protocols       TLSv1 TLSv1.1 TLSv1.2;
        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;

        ...
    }
```

## 指令 <a href="#directives" id="directives"></a>

### ssl

| -       | 说明                     |
| ------- | ---------------------- |
| **语法**  | **ssl** `on` \| `off`; |
| **默认**  | ssl off;               |
| **上下文** | mail、server            |

该指令在 1.15.0 版本中已废弃，请改用 [listen](/nginx-docs/he-xin-gong-neng/mail/ngx_mail_core_module.md#listen) 指令的 `ssl` 参数。

### ssl\_certificate

| -       | 说明                           |
| ------- | ---------------------------- |
| **语法**  | **ssl\_certificate** `file`; |
| **默认**  | ——                           |
| **上下文** | mail、server                  |

为给定服务器指定一个 PEM 格式的证书文件（`file`）。如果除主证书之外还要指定中间证书，则应在同一文件中按以下顺序指定它们：首先是主证书，然后是中间证书。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 或更高版本支持不同证书的独立证书链。对于较旧的版本，只能使用一个证书链。

可以指定 `data:certificate` 值来代替 `file`（1.15.10），无需使用文件即可加载证书。请注意，错误使用此语法可能会带来安全隐患，例如将密钥数据写入[错误日志](/nginx-docs/he-xin-gong-neng.md#error_log)。

### ssl\_certificate\_key

| -       | 说明                                |
| ------- | --------------------------------- |
| **语法**  | **ssl\_certificate\_key** `file`; |
| **默认**  | ——                                |
| **上下文** | mail、server                       |

给服务器指定一个 PEM 格式的密钥文件（`file`）。

可以指定 `engine:name:id` 来代替 `file`（1.7.9），Nginx 将从名称为 `name` 的 OpenSSL 引擎中中加载 id 为 `id` 的密钥。

可以指定 `data:key` 值来代替 `file`（1.15.10），无需使用文件就可以加载密钥。请注意，错误使用此语法可能会带来安全隐患，例如将密钥数据写入[错误日志](/nginx-docs/he-xin-gong-neng.md#error_log)。

### 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 ciphers` 命令查看完整列表。

默认情况下，早期版本的 nginx 使用了[不同](/nginx-docs/readme/pei-zhi-https-fu-wu-qi.md#compatibility)的加密算法。

### ssl\_client\_certificate

| -       | 说明                                   |
| ------- | ------------------------------------ |
| **语法**  | **ssl\_client\_certificate** `file`; |
| **默认**  | ——                                   |
| **上下文** | mail、server                          |
| **提示**  | 该指令在 1.7.11 版本中出现                    |

指定一个 PEM 格式的受信任 CA 证书文件，用于[验证](/nginx-docs/he-xin-gong-neng/mail/ngx_mail_ssl_module.md#ssl_verify_client)客户端证书。

证书列表将发送给客户端。如果不希望这样做，则可以使用 [ssl\_trusted\_certificate ](/nginx-docs/he-xin-gong-neng/mail/ngx_mail_ssl_module.md#ssl_trusted_certificate) 指令配置。

### ssl\_crl

| -       | 说明                   |
| ------- | -------------------- |
| **语法**  | **ssl\_crl** `file`; |
| **默认**  | ——                   |
| **上下文** | mail、server          |
| **提示**  | 该指令在 1.7.11 版本中出现    |

指定一个 PEM 格式的吊销证书（CRL）文件，用于[验证](/nginx-docs/he-xin-gong-neng/mail/ngx_mail_ssl_module.md#ssl_verify_client)客户端证书。

### ssl\_dhparam

| -       | 说明                       |
| ------- | ------------------------ |
| **语法**  | **ssl\_dhparam** `file`; |
| **默认**  | ——                       |
| **上下文** | mail、server              |
| **提示**  | 该指令在 0.7.2 版本中出现         |

指定一个带有 DHE 密码的 DH 参数的文件（`file`）。

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

> 在 1.11.0 版之前，默认情况下使用内置参数。

### ssl\_ecdh\_curve

| -       | 说明                            |
| ------- | ----------------------------- |
| **语法**  | **ssl\_ecdh\_curve** `curve`; |
| **默认**  | ssl\_ecdh\_curve auto;        |
| **上下文** | mail、server                   |
| **提示**  | 该指令在 1.1.0 和 1.0.6 版本中出现      |

为 ECDHE 算法指定一个椭圆曲线方案（`curve`）。

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

```
ssl_ecdh_curve prime256v1:secp384r1;
```

当使用 OpenSSL 1.0.2 或更高版本或带有较旧版本的 `prime256v1` 时，特殊值 `auto`（1.11.0）指示 nginx 使用内置在 OpenSSL 库中的列表。

> 在 1.11.0 版之前，默认使用 `prime256v1` 曲线。

### ssl\_password\_file

| -       | 说明                              |
| ------- | ------------------------------- |
| **语法**  | **ssl\_password\_file** `file`; |
| **默认**  | ——                              |
| **上下文** | mail、server                     |
| **提示**  | 该指令在 1.7.3 版本中出现                |

指定一个保存有[密钥](/nginx-docs/he-xin-gong-neng/mail/ngx_mail_ssl_module.md#ssl_certificate_key)密码的文件，每个密码独占一行。 加载密钥时依次尝试使用这些密码。

例：

```
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;
    }
}
```

### ssl\_prefer\_server\_ciphers

| -       | 说明                                              |
| ------- | ----------------------------------------------- |
| **语法**  | **ssl\_prefer\_server\_ciphers** `on` \| `off`; |
| **默认**  | ssl\_prefer\_server\_ciphers off;               |
| **上下文** | mail、server                                     |

指定当使用 SSLv3 和 TLS 协议时，服务器加密算法应优先于客户端加密算法。

### ssl\_protocols

| -       | 说明                                                               |
| ------- | ---------------------------------------------------------------- |
| **语法**  | **ssl** `[SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3]`; |
| **默认**  | sssl\_protocols TLSv1 TLSv1.1 TLSv1.2;                           |
| **上下文** | mail、server                                                      |

启用指定的协议。

> `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 支持有效。

### ssl\_session\_cache

| -       | 说明                                                                               |
| ------- | -------------------------------------------------------------------------------- |
| **语法**  | **ssl\_session\_cache** `on` \| `none` \| `[builtin[:size]] [shared:name:size]`; |
| **默认**  | ssl\_session\_cache none;                                                        |
| **上下文** | mail、server                                                                      |

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

* `off`

  严格禁止使用会话缓存：nginx 明确告知客户端禁止重复使用会话。
* `none`

  禁止使用会话缓存：nginx 告诉客户端会话可以重用，但实际上并没有在缓存中存储会话参数。
* `builtin`

  内置的 OpenSSL 缓存，仅由一个 worker 进程使用。缓存大小在会话中指定。如果未指定大小，则默认为 20480 个会话。使用内置缓存可能导致内存碎片。
* `shared`

  所有 worker 进程之间共享的缓存。缓存大小以字节为单位，一兆字节可以存储大约 4000 个会话。每个共享缓存都有一个任意的名称。相同名称的缓存可以在多个服务器中使用。

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

```
ssl_session_cache builtin:1000 shared:SSL:10m;
```

但仅使用共享缓存而不使用内置缓存，效率会更高。

### ssl\_session\_ticket\_key

| -       | 说明                                    |
| ------- | ------------------------------------- |
| **语法**  | **ssl\_session\_ticket\_key** `file`; |
| **默认**  | ——                                    |
| **上下文** | mail、server                           |
| **提示**  | 该指令在 1.5.7 版本中出现                      |

设置一个带有用于加密和解密 TLS 会话票证的密钥文件。如果必须在多个服务器之间共享同一密钥，则该指令是必需的。默认情况下，使用随机生成的密钥。

如果指定了多个密钥，仅第一个密钥被用于加密 TLS 会话票证。可配置 key 轮转，例如：

```
ssl_session_ticket_key current.key;
ssl_session_ticket_key previous.key;
```

该文件（`file`）必须包含 80 或 48 个字节的随机数据，可以使用以下命令创建：

```
openssl rand 80> ticket.key
```

根据文件大小，使用 AES256（针对 80 字节的 key，1.11.8）或 AES128（针对 48 字节的 key）进行加密。

### ssl\_session\_tickets

| -       | 说明                                       |
| ------- | ---------------------------------------- |
| **语法**  | **ssl\_session\_tickets** `on` \| `off`; |
| **默认**  | ssl\_session\_tickets on;                |
| **上下文** | mail、server                              |
| **提示**  | 该指令在 1.5.9 版本中出现                         |

通过 [TLS 会话票证](https://tools.ietf.org/html/rfc5077)启用或禁用会话复用。

### ssl\_session\_timeout

| -       | 说明                                |
| ------- | --------------------------------- |
| **语法**  | **ssl\_session\_timeout** `time`; |
| **默认**  | ssl\_session\_timeout 5m;         |
| **上下文** | mail、server                       |

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

### ssl\_trusted\_certificate

| -       | 说明                                    |
| ------- | ------------------------------------- |
| **语法**  | **ssl\_trusted\_certificate** `file`; |
| **默认**  | ——                                    |
| **上下文** | mail、server                           |
| **提示**  | 该指令在 1.7.11 版本中出现                     |

指定一个带有用于[验证](/nginx-docs/he-xin-gong-neng/mail/ngx_mail_ssl_module.md#ssl_verify_client)客户端证书的 PEM 格式的受信任 CA 证书文件。

与 [ssl\_client\_certificate](/nginx-docs/he-xin-gong-neng/mail/ngx_mail_ssl_module.md#ssl_client_certificate) 设置的证书相反，这些证书的列表不会发送给客户端。

### ssl\_verify\_client

| -       | 说明                                                                        |
| ------- | ------------------------------------------------------------------------- |
| **语法**  | **ssl\_verify\_client** `on` \| `none` \| `optional` \| `optional_no_ca`; |
| **默认**  | ssl\_verify\_client off;                                                  |
| **上下文** | mail、server                                                               |
| **提示**  | 该指令在 1.7.11 版本中出现                                                         |

启用客户端证书的验证。验证结果在[身份验证](/nginx-docs/he-xin-gong-neng/mail/ngx_mail_auth_http_module.md#auth_http)请求的 **Auth-SSL-Verify** 头中传递。

`optional` 参数请求客户端证书并验证该证书是否存在。

`optional_no_ca` 参数请求客户端证书，但不需要由受信任的 CA 证书对其进行签名，适合在 nginx 外部的服务执行实际证书验证的情况下使用。通过[发送](/nginx-docs/he-xin-gong-neng/mail/ngx_mail_auth_http_module.md#auth_http_pass_client_cert)到身份验证服务器的请求可以访问证书的内容。

### ssl\_verify\_depth

| -       | 说明                               |
| ------- | -------------------------------- |
| **语法**  | **ssl\_verify\_depth** `number`; |
| **默认**  | ssl\_verify\_depth 1;            |
| **上下文** | mail、server                      |
| **提示**  | 该指令在 1.7.11 版本中出现                |

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

### starttls

| -       | 说明                                    |
| ------- | ------------------------------------- |
| **语法**  | **starttls** `on` \| `off` \| `only`; |
| **默认**  | starttls off;                         |
| **上下文** | mail、server                           |

* `on`

  允许对 POP3 使用 `STLS` 命令，对 IMAP 和 SMTP 使用 `STARTTLS` 命令
* `off`

  拒绝使用 `STLS` 和 `STARTTLS` 命令
* `only`

  要求初步的 TLS 转换

## 原文档

* <http://nginx.org/en/docs/mail/ngx_mail_ssl_module.html>