<!-- review: finished -->

<a id="http-ssl"></a>

# SSL

提供 HTTPS 所需的支持。

当从 [源代码构建](https://cn.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild) 时,
此模块默认不会被构建;
应使用
`‑‑with‑http_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 库。

<a id="configuration-example-42"></a>

## 配置示例

为了降低处理器负载,建议

* 将 [工作进程](https://cn.angie.software//angie/docs/configuration/modules/core.md#worker-processes) 数量设置为等于处理器数量,
* 启用 [keep-alive](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#keepalive-timeout) 连接,
* 启用 [共享](#ssl-session-cache) 会话缓存,
* 禁用 [内置](#ssl-session-cache) 会话缓存,
* 并可能增加会话 [生命周期](#ssl-session-timeout) (默认为 5 分钟):

```nginx
worker_processes auto;

http {

    # ...

    server {
        listen              443 ssl;
        keepalive_timeout   70;

        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;

        # ...
    }
```

<a id="directives-45"></a>

## 指令

<a id="index-0"></a>

<a id="ssl-buffer-size"></a>

### ssl_buffer_size

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_buffer_size` size;   |
|--------------------------------------------------------------------------------------|---------------------------|
| 默认值                                                                                  | `ssl_buffer_size 16k;`    |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server              |

设置用于发送数据的缓冲区大小。

默认情况下,缓冲区大小为 16k,这对应于发送大响应时的最小开销。为了最小化首字节时间,使用较小的值可能是有益的,例如:

```nginx
ssl_buffer_size 4k;
```

<a id="index-1"></a>

<a id="ssl-certificate"></a>

### 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)  | http, server              |

为给定的虚拟服务器指定 PEM 格式的证书文件。如果除了主证书之外还应指定中间证书,则应按以下顺序在同一文件中指定它们:首先是主证书,然后是中间证书。PEM 格式的私钥可以放在同一文件中。

此指令可以多次指定以加载不同类型的证书,例如 RSA 和 ECDSA:

```nginx
server {
    listen              443 ssl;
    server_name         example.com;

    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 或更高版本支持为不同证书使用单独的证书链。对于较旧的版本,只能使用一个证书链。

#### NOTE
使用 OpenSSL 1.0.2 或更高版本时,可以在文件名中使用变量:

```nginx
ssl_certificate     $ssl_server_name.crt;
ssl_certificate_key $ssl_server_name.key;
```

请注意,使用变量意味着将为每次 SSL 握手加载证书,这可能会对性能产生负面影响。

可以指定值 `data:$variable` 来代替 file,这将从变量加载证书而不使用中间文件。请注意,不当使用此语法可能会带来安全隐患,例如将私钥数据写入 [错误日志](https://cn.angie.software//angie/docs/configuration/modules/core.md#error-log)。

#### NOTE
> 应该记住,由于 HTTPS 协议的限制,为了最大的互操作性,虚拟服务器应该监听 [不同的 IP 地址](https://cn.angie.software//angie/docs/configuration/ssl.md#https-separate-ips)。

如果启用了 [ssl_ntls](#ssl-ntls),该指令可以接受两个参数
(证书的签名部分和加密部分)
而不是一个:

```nginx
listen ... ssl;

ssl_ntls  on;

# 双 NTLS 证书
ssl_certificate      sign.crt enc.crt;
ssl_certificate_key  sign.key enc.key;

# 可以与常规 RSA 证书一起使用
ssl_certificate  rsa.crt;
ssl_certificate_key rsa.key;
```

<a id="index-2"></a>

<a id="ssl-certificate-cache"></a>

### ssl_certificate_cache

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_certificate_cache` `off`;<br/><br/>`ssl_certificate_cache` `max=`N [`inactive=`time] [`valid=`time];   |
|--------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------|
| 默认值                                                                                  | `ssl_certificate_cache off;`                                                                                |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                                                                                                |

定义一个缓存,用于存储使用变量指定的 [SSL 证书](#ssl-certificate) 和 [私钥](#ssl-certificate-key)。

该指令支持以下参数:

- `max` — 设置缓存中的最大元素数量。当缓存溢出时,
  最近最少使用 (LRU) 的元素将被移除。
- `inactive` — 定义元素在未被访问的情况下被移除的时间。
  默认为 10 秒。
- `valid` — 定义缓存元素被视为有效并可以重用的时间。
  默认为 60 秒。在此期间之后,
  证书将被重新加载或重新验证。
- `off` — 禁用缓存。

示例:

```nginx
ssl_certificate       $ssl_server_name.crt;
ssl_certificate_key   $ssl_server_name.key;
ssl_certificate_cache max=1000 inactive=20s valid=1m;
```

<a id="index-3"></a>

<a id="ssl-certificate-compression"></a>

### 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)  | http, server                                  |

启用 TLS 1.3 服务器证书 [压缩](https://datatracker.ietf.org/doc/html/rfc8879)。

#### NOTE
在使用 OpenSSL 3.2 或更高版本时支持该指令;支持的压缩算法列表由库提供。

#### NOTE
在使用 [BoringSSL](https://boringssl.googlesource.com/boringssl/) 时支持该指令;支持的压缩算法列表包括 `zlib`。

如果启用了 [ssl_stapling](#ssl-stapling),则禁用证书压缩。

<a id="index-4"></a>

<a id="ssl-certificate-key"></a>

### 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)  | http, server                  |

为给定的虚拟服务器指定 PEM 格式的私钥文件。

#### NOTE
使用 OpenSSL 1.0.2 或更高版本时,可以在文件名中使用变量。

可以指定值 `engine:name:id` 来代替 file,这将从 OpenSSL 引擎 name 加载具有指定 id 的私钥。

可以指定值 `store:scheme:id` 来代替 file,用于从具有指定 id 和 OpenSSL 提供程序注册的 URI scheme 加载私钥,例如 [pkcs11](https://datatracker.ietf.org/doc/html/rfc7512)。

可以指定值 `data:$variable` 来代替 file,这将从变量加载私钥而不使用中间文件。请注意,不当使用此语法可能会带来安全隐患,例如将私钥数据写入 [错误日志](https://cn.angie.software//angie/docs/configuration/modules/core.md#error-log)。

> 如果启用了 [ssl_ntls](#ssl-ntls),该指令可以接受两个参数
> (密钥的签名部分和加密部分)
> 而不是一个:

> ```nginx
> listen ... ssl;

> ssl_ntls  on;

> # 双 NTLS 证书
> ssl_certificate      sign.crt enc.crt;
> ssl_certificate_key  sign.key enc.key;

> # 可以与常规 RSA 证书一起使用
> ssl_certificate  rsa.crt;
> ssl_certificate_key rsa.key;
> ```

<a id="index-5"></a>

<a id="ssl-ciphers"></a>

### 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)  | http, 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](#ssl-conf-command) 指令,该指令是为支持高级
SSL 配置而添加的。

- 在 LibreSSL 中,TLS 1.3 密码套件  *可以* 使用
  `ssl_ciphers` 配置。
- 在 BoringSSL 中,TLS 1.3 密码套件根本无法配置。

<a id="index-6"></a>

<a id="ssl-client-certificate"></a>

### 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)  | http, server                     |

指定 PEM 格式的受信任 CA 证书文件,用于
[验证](#ssl-verify-client) 客户端证书,以及在启用
[ssl_stapling](#ssl-stapling) 时验证 OCSP 响应。

证书列表将发送给客户端。如果不希望这样做,可以使用 [ssl_trusted_certificate](#ssl-trusted-certificate) 指令。

<a id="index-7"></a>

<a id="ssl-conf-command"></a>

### 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)  | http, 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 可能导致意外行为。

<a id="index-8"></a>

<a id="ssl-crl"></a>

### 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)  | http, server      |

指定用于 [验证](#ssl-verify-client) 客户端证书的 PEM 格式吊销证书 (CRL) 文件。

<a id="index-9"></a>

<a id="ssl-dhparam"></a>

### 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)  | http, server          |

指定一个包含 DHE 密码套件的 DH 参数的文件。

默认情况下不设置参数,因此不会使用 DHE 密码套件。

<a id="index-10"></a>

<a id="ssl-early-data"></a>

### ssl_early_data

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_early_data` `on` | `off`;   |
|--------------------------------------------------------------------------------------|----------------------------------|
| 默认值                                                                                  | `ssl_early_data off;`            |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                     |

启用或禁用 TLS 1.3 [早期数据](https://datatracker.ietf.org/doc/html/rfc8446#section-2.3)。

在早期数据中发送的请求会受到 [重放攻击](https://datatracker.ietf.org/doc/html/rfc8470) 的影响。为了保护应用层免受此类攻击,应使用 [$ssl_early_data](#v-ssl-early-data) 变量。

```nginx
proxy_set_header Early-Data $ssl_early_data;
```

#### NOTE
在使用 OpenSSL 1.1.1 或更高版本以及 [BoringSSL](https://boringssl.googlesource.com/boringssl/) 时支持该指令。

<a id="index-11"></a>

<a id="ssl-encrypted-hello-key"></a>

### ssl_encrypted_hello_key

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_encrypted_hello_key` file;   |
|--------------------------------------------------------------------------------------|-----------------------------------|
| 默认值                                                                                  | —                                 |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                      |

指定一个包含 PEM 格式的 ECH 私钥和 ECHConfigList 的文件。
该指令可以指定多次。
需要支持加密客户端问候 (ECH) 的 OpenSSL 或 BoringSSL 构建;
否则不支持。

<a id="index-12"></a>

<a id="ssl-ecdh-curve"></a>

### 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)  | http, server              |

指定 ECDHE 密码套件的曲线。

#### NOTE
在使用 OpenSSL 1.0.2 或更高版本时,可以指定多个曲线,例如:

```nginx
ssl_ecdh_curve prime256v1:secp384r1;
```

特殊值 `auto` 对应于 OpenSSL 1.0.2 或更高版本中 OpenSSL 库内置的曲线列表,或者在较旧版本中对应于 prime256v1。

#### NOTE
在使用 OpenSSL 1.0.2 或更高版本时,该指令设置服务器支持的曲线列表。因此,为了使 ECDSA 证书能够正常工作,重要的是要包括证书中使用的曲线。

<a id="index-13"></a>

<a id="ssl-ntls"></a>

### ssl_ntls

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_ntls` `on` | `off`;   |
|--------------------------------------------------------------------------------------|----------------------------|
| 默认值                                                                                  | `ssl_ntls off;`            |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server               |

在使用 [TongSuo](https://github.com/Tongsuo-Project/Tongsuo) TLS 库时启用服务器端对 NTLS 的支持。

```nginx
listen ... ssl;
ssl_ntls  on;
```

#### NOTE
必须使用 `--with-ntls` 配置参数构建 Angie,并使用相应的支持 NTLS 的 SSL 库

```default
./configure --with-openssl=../Tongsuo-8.3.0 \
            --with-openssl-opt=enable-ntls  \
            --with-ntls
```

<a id="index-14"></a>

<a id="ssl-ocsp"></a>

### ssl_ocsp

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_ocsp` `on` | `off` | `leaf`;   |
|--------------------------------------------------------------------------------------|-------------------------------------|
| 默认值                                                                                  | `ssl_ocsp off;`                     |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                        |

启用客户端证书链的 OCSP 验证。`leaf` 参数仅启用客户端证书的验证。

为了使 OCSP 验证正常工作,:ref:ssl_verify_client 指令应设置为 `on` 或 `optional`。

要解析 OCSP 响应者主机名,也应指定 [resolver](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#resolver) 指令。

示例：

```nginx
ssl_verify_client on;
ssl_ocsp          on;
resolver          127.0.0.53;
```

<a id="index-15"></a>

<a id="ssl-ocsp-cache"></a>

### ssl_ocsp_cache

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_ocsp_cache` `off` | [shared:name:size];   |
|--------------------------------------------------------------------------------------|------------------------------------------------|
| 默认值                                                                                  | `ssl_ocsp_cache off;`                          |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                                   |

设置存储客户端证书状态以进行 OCSP 验证的缓存的名称和大小。该缓存在所有工作进程之间共享。可以在多个虚拟服务器中使用相同名称的缓存。

`off` 参数禁止使用缓存。

<a id="index-16"></a>

<a id="ssl-ocsp-responder"></a>

### ssl_ocsp_responder

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_ocsp_responder` uri;   |
|--------------------------------------------------------------------------------------|-----------------------------|
| 默认值                                                                                  | —                           |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                |

覆盖在 ["Authority Information Access"](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.2.1) 证书扩展中指定的 OCSP 响应者的 URI,用于 [验证](#ssl-ocsp) 客户端证书。

仅支持 `http://` OCSP 响应者:

```nginx
ssl_ocsp_responder http://ocsp.example.com/;
```

<a id="index-17"></a>

<a id="ssl-password-file"></a>

### 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)  | http, server                |

指定一个包含 [私钥](#ssl-certificate-key) 密码短语的文件,每个密码短语在单独的一行中指定。加载密钥时将依次尝试密码短语。

示例:

```nginx
http {
    ssl_password_file /etc/keys/global.pass;
    ...

    server {
        server_name www1.example.com;
        ssl_certificate_key /etc/keys/first.key;
    }

    server {
        server_name www2.example.com;

        # 也可以使用命名管道代替文件
        ssl_password_file /etc/keys/fifo;
        ssl_certificate_key /etc/keys/second.key;
    }
}
```

<a id="index-18"></a>

<a id="ssl-prefer-server-ciphers"></a>

### 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)  | http, server                                |

指定在使用 SSLv3 和 TLS 协议时,服务器密码套件应优于客户端密码套件。

<a id="index-19"></a>

<a id="ssl-protocols"></a>

### 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)  | http, server                                                                         |

#### Versionchanged
在 1.2.0 版本发生变更: `TLSv1.3` 参数被添加到默认集合中。

启用指定的协议。

#### NOTE
TLSv1.1 和 TLSv1.2 参数仅在使用 OpenSSL 1.0.1 或更高版本时有效。

TLSv1.3 参数仅在使用 OpenSSL 1.1.1 或更高版本时有效。

<a id="index-20"></a>

<a id="ssl-reject-handshake"></a>

### ssl_reject_handshake

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_reject_handshake` `on` | `off`;   |
|--------------------------------------------------------------------------------------|----------------------------------------|
| 默认值                                                                                  | `ssl_reject_handshake off;`            |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                           |

如果启用,:ref:server 块中的 SSL 握手将被拒绝。

例如,在以下配置中,与服务器名称不是 example.com 的 SSL 握手将被拒绝:

```nginx
server {
    listen               443 ssl default_server;
    ssl_reject_handshake on;
}

server {
    listen              443 ssl;
    server_name         example.com;
    ssl_certificate     example.com.crt;
    ssl_certificate_key example.com.key;
}
```

<a id="index-21"></a>

<a id="ssl-session-cache"></a>

### 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)  | http, server                                                                |

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

| `off`     | 严格禁止使用会话缓存：Angie 明确告知客户端会话不可重用。                                                                                                                                                    |
|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `none`    | 温和地禁止使用会话缓存：Angie 告知客户端会话可以重用，但实际上不在缓存中存储会话参数。                                                                                                                                     |
| `builtin` | OpenSSL 内置缓存；仅由一个工作进程使用。缓存大小以会话数指定。如果未指定大小，则等于 20480 个会话。使用内置缓存可能导致内存碎片。                                                                                                           |
| `shared`  | 在所有工作进程之间共享的缓存。缓存大小以字节为单位指定；1 兆字节可以存储约 4000 个会话。每个共享缓存应有一个任意名称。具有相同名称的缓存可以在多个虚拟服务器中使用。除非使用 [ssl_session_ticket_key](#ssl-session-ticket-key) 指令显式配置，否则它还用于自动生成、存储和定期轮换 TLS 会话票据密钥。 |

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

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

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

<a id="index-22"></a>

<a id="ssl-session-ticket-key"></a>

### 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)  | http, 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 字节密钥）进行加密。

<a id="index-23"></a>

<a id="ssl-session-tickets"></a>

### 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)  | http, server                          |

启用或禁用通过 [TLS 会话票据](https://datatracker.ietf.org/doc/html/rfc5077) 进行会话恢复。

<a id="index-24"></a>

<a id="ssl-session-timeout"></a>

### 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)  | http, server                  |

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

<a id="index-25"></a>

<a id="ssl-stapling"></a>

### ssl_stapling

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_stapling` `on` | `off`;   |
|--------------------------------------------------------------------------------------|--------------------------------|
| 默认值                                                                                  | `ssl_stapling off;`            |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                   |

启用或禁用服务器 [装订 OCSP 响应](https://datatracker.ietf.org/doc/html/rfc6066#section-8)。示例：

```nginx
ssl_stapling on;
resolver 127.0.0.53;
```

要使 OCSP 装订正常工作，应该知道服务器证书颁发者的证书。如果 [ssl_certificate](#ssl-certificate) 文件不包含中间证书，则服务器证书颁发者的证书应存在于 [ssl_trusted_certificate](#ssl-trusted-certificate) 指令指定的文件中。

#### WARNING
为了解析 OCSP 响应者主机名，还应指定 [resolver](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#resolver) 指令。

<a id="index-26"></a>

<a id="ssl-stapling-file"></a>

### ssl_stapling_file

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_stapling_file` file;   |
|--------------------------------------------------------------------------------------|-----------------------------|
| 默认值                                                                                  | —                           |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                |

设置后，装订的 OCSP 响应将从指定的文件中获取，而不是查询服务器证书中指定的 OCSP 响应者。

该文件应为 DER 格式，由 `openssl ocsp` 命令生成。

<a id="index-27"></a>

<a id="ssl-stapling-responder"></a>

### ssl_stapling_responder

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_stapling_responder` `uri`;   |
|--------------------------------------------------------------------------------------|-----------------------------------|
| 默认值                                                                                  | —                                 |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                      |

覆盖证书扩展 ["Authority Information Access"](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.2.1) 中指定的 OCSP 响应者的 URI。

仅支持 `http://` OCSP 响应者：

```nginx
ssl_stapling_responder http://ocsp.example.com/;
```

<a id="index-28"></a>

<a id="ssl-stapling-verify"></a>

### ssl_stapling_verify

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ssl_stapling_verify` `on` | `off`;   |
|--------------------------------------------------------------------------------------|---------------------------------------|
| 默认值                                                                                  | `ssl_stapling_verify off;`            |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                          |

启用或禁用服务器对 OCSP 响应的验证。

要使验证正常工作，应使用 [ssl_trusted_certificate](#ssl-trusted-certificate) 指令将服务器证书颁发者的证书、根证书和所有中间证书配置为受信任。

<a id="index-29"></a>

<a id="ssl-trusted-certificate"></a>

### 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)  | http, server                      |

指定包含 PEM 格式受信任 CA 证书的文件，用于 [验证](#ssl-verify-client) 客户端证书，以及在启用 [ssl_stapling](#ssl-stapling) 时验证 OCSP 响应。

与 [ssl_client_certificate](#ssl-client-certificate) 设置的证书集不同，这些证书的列表不会发送给客户端。

<a id="index-30"></a>

<a id="ssl-verify-client"></a>

### 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)  | http, server                                                        |

启用客户端证书验证。验证结果存储在 [$ssl_client_verify](#v-ssl-client-verify) 变量中。

| `optional`       | 请求客户端证书，如果证书存在则进行验证。                                     |
|------------------|----------------------------------------------------------|
| `optional_no_ca` | 请求客户端证书，但不要求其由受信任的 CA 证书签名。这适用于由 Angie 外部的服务执行实际证书验证的情况。 |

<a id="index-31"></a>

<a id="ssl-verify-depth"></a>

### 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)  | http, server                 |

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

<a id="ssl-error-codes"></a>

## 错误处理

`http_ssl` 模块支持几个非标准错误代码，可以使用 [error_page](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#error-page) 指令进行重定向：

| `495`   | 客户端证书验证过程中发生错误；    |
|---------|--------------------|
| `496`   | 客户端未提供所需的证书；       |
| `497`   | 常规请求已发送到 HTTPS 端口。 |

重定向发生在请求完全解析之后，此时变量（如 [$request_uri](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#v-request-uri)、[$uri](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#v-uri)、[$args](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#v-args) 等）已可用。

<a id="built-in-variables-12"></a>

## 内置变量

http_ssl 模块支持内置变量：

<a id="v-ssl-alpn-protocol"></a>

### `$ssl_alpn_protocol`

返回在 SSL 握手期间通过 ALPN 选择的协议，否则返回空字符串。

<a id="v-ssl-cipher"></a>

### `$ssl_cipher`

返回已建立的 SSL 连接所使用的密码套件名称。

<a id="v-ssl-ciphers"></a>

### `$ssl_ciphers`

返回客户端支持的密码套件列表。已知的密码套件按名称列出，未知的以十六进制显示，例如：

> AES128-SHA:AES256-SHA:0x00ff

#### NOTE
仅在使用 OpenSSL 1.0.2 或更高版本时才完全支持该变量。对于较旧版本，该变量仅适用于新会话，并且仅列出已知的密码套件。

<a id="v-ssl-client-escaped-cert"></a>

### `$ssl_client_escaped_cert`

返回已建立的 SSL 连接的 PEM 格式客户端证书（URL 编码）。

<a id="v-ssl-client-fingerprint"></a>

### `$ssl_client_fingerprint`

返回已建立的 SSL 连接的客户端证书的 SHA1 指纹。

<a id="v-ssl-client-i-dn"></a>

### `$ssl_client_i_dn`

根据 [RFC 2253](https://datatracker.ietf.org/doc/html/rfc2253) 返回已建立的 SSL 连接的客户端证书的"颁发者 DN"字符串。

<a id="v-ssl-client-i-dn-legacy"></a>

### `$ssl_client_i_dn_legacy`

返回已建立的 SSL 连接的客户端证书的"颁发者 DN"字符串。

<a id="v-ssl-client-raw-cert"></a>

### `$ssl_client_raw_cert`

返回已建立的 SSL 连接的 PEM 格式客户端证书。

<a id="v-ssl-client-s-dn"></a>

### `$ssl_client_s_dn`

根据 [RFC 2253](https://datatracker.ietf.org/doc/html/rfc2253) 返回已建立的 SSL 连接的客户端证书的"主题 DN"字符串。

<a id="v-ssl-client-s-dn-legacy"></a>

### `$ssl_client_s_dn_legacy`

返回已建立的 SSL 连接的客户端证书的"主题 DN"字符串。

<a id="v-ssl-client-serial"></a>

### `$ssl_client_serial`

返回已建立的 SSL 连接的客户端证书的序列号。

<a id="v-ssl-client-sigalg"></a>

### `$ssl_client_sigalg`

返回已建立的 SSL 连接的客户端证书的\`签名算法 <[https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-16](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-16)>\`_。

#### NOTE
仅在使用 OpenSSL 3.5 或更高版本时才支持该变量。对于较旧版本，该变量值将为空字符串。

#### NOTE
该变量仅适用于新会话。

<a id="v-ssl-client-v-end"></a>

### `$ssl_client_v_end`

返回客户端证书的结束日期。

<a id="v-ssl-client-v-remain"></a>

### `$ssl_client_v_remain`

返回客户端证书到期前的剩余天数。

<a id="v-ssl-client-v-start"></a>

### `$ssl_client_v_start`

返回客户端证书的开始日期。

<a id="v-ssl-client-verify"></a>

### `$ssl_client_verify`

返回客户端证书验证的结果：`SUCCESS`、`FAILED:reason`，如果未提供证书则返回 `NONE`。

<a id="v-ssl-curve"></a>

### `$ssl_curve`

返回在 SSL 握手期间用于密钥交换的协商曲线。已知的曲线按名称列出，未知的以十六进制显示，例如：

> prime256v1

#### NOTE
仅在使用 OpenSSL 3.0 或更高版本时才支持该变量。对于较旧版本，该变量值将为空字符串。

<a id="v-ssl-curves"></a>

### `$ssl_curves`

返回客户端支持的曲线列表。已知的曲线按名称列出，未知的以十六进制显示，例如：

> 0x001d:prime256v1:secp521r1:secp384r1

#### NOTE
仅在使用 OpenSSL 1.0.2 或更高版本时才支持该变量。对于较旧版本，该变量值将为空字符串。

该变量仅适用于新会话。

<a id="v-ssl-early-data"></a>

### `$ssl_early_data`

如果使用 TLS 1.3 [早期数据](#ssl-early-data) 且握手未完成，则返回"1"，否则返回""。

<a id="v-ssl-encrypted-hello"></a>

### `$ssl_encrypted_hello`

如果使用加密客户端问候（ECH），则返回"1"，否则返回""。

<a id="v-ssl-protocol"></a>

### `$ssl_protocol`

返回已建立的 SSL 连接的协议。

<a id="v-ssl-server-cert-type"></a>

### `$ssl_server_cert_type`

根据服务器证书和密钥的类型，取值为 `RSA`、`DSA`、`ECDSA`、`ED448`、
`ED25519`、`SM2`、`RSA-PSS` 或 `unknown`。

<a id="v-ssl-server-name"></a>

### `$ssl_server_name`

返回通过 [SNI](http://en.wikipedia.org/wiki/Server_Name_Indication) 请求的服务器名称。

<a id="v-ssl-session-id"></a>

### `$ssl_session_id`

返回已建立的 SSL 连接的会话标识符。

<a id="v-ssl-session-reused"></a>

### `$ssl_session_reused`

如果 SSL 会话被重用，则返回"r"，否则返回"."。

<a id="v-ssl-sigalg"></a>

### `$ssl_sigalg`

返回已建立的 SSL 连接的服务器证书的\`签名算法 <[https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-16](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-16)>\`_。

#### NOTE
仅在使用 OpenSSL 3.5 或更高版本时才支持该变量。对于较旧版本，该变量值将为空字符串。

#### NOTE
该变量仅适用于新会话。