SSL#
提供必要的HTTPS支持。
当从 源代码构建 时，
此模块默认未构建；
可以通过使用
‑‑with‑http_ssl_module
构建选项 来启用它。
在来自 我们仓库 的软件包和镜像中， 该模块已包含在构建中。
重要
此模块需要OpenSSL库。
配置示例#
为了减少处理器负载，建议
worker_processes auto;
http {
# ...
server {
listen 443 ssl;
keepalive_timeout 70;
ssl_protocols TLSv1 TLSv1.1 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_buffer_size#
设置用于发送数据的缓冲区大小。
默认情况下，缓冲区大小为16k，这在发送大响应时对应于最小开销。为了最小化首字节时间，可以使用较小的值，例如：
ssl_buffer_size 4k;
ssl_certificate#
指定具有PEM格式证书的文件用于给定的虚拟服务器。如果除了主证书还应指定中间证书，则应按以下顺序在同一文件中指定：首先是主证书，然后是中间证书。可以将PEM格式的私钥放在同一文件中。
此指令可以多次指定以加载不同类型的证书，例如RSA和ECDSA：
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或更高版本支持为不同证书提供单独的证书链。对于旧版本，只能使用一个证书链。
重要
使用OpenSSL 1.0.2或更高版本时，可以在文件名中使用变量：
ssl_certificate $ssl_server_name.crt;
ssl_certificate_key $ssl_server_name.key;
注意，使用变量意味着每次SSL握手都会加载一个证书，这可能对性能产生负面影响。
可以将值 "data:$variable" 指定为 file，它从变量中加载证书而不使用中间文件。注意，不当使用此语法可能具有安全隐患，例如将密钥数据写入 错误日志。
重要
应该记住，由于HTTPS协议限制，为了最大兼容性，虚拟服务器应监听在 不同的IP地址。
Added in version 1.2.0: 如果 ssl_ntls 已启用，指令可以接受两个参数 （密钥的签名和加密部分） 而不是一个：
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 rsa.key;
ssl_certificate_key#
指定具有PEM格式私钥的文件用于给定的虚拟服务器。
重要
使用OpenSSL 1.0.2或更高版本时，可以在文件名中使用变量。
可以将值 "engine:name:id" 指定为 file，它从OpenSSL引擎名中加载具有指定 id 的私钥。
可以将值 "data:$variable" 指定为 file，它从变量中加载私钥而不使用中间文件。注意，不当使用此语法可能具有安全隐患，例如将密钥数据写入 错误日志。
Added in version 1.2.0: 如果 ssl_ntls 已启用，指令可以接受两个参数 （密钥的签名和加密部分） 而不是一个：
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 rsa.key;
ssl_ciphers#
指定启用的密码。密码格式为OpenSSL库理解的格式，例如：
ssl_ciphers ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;
可以使用 "openssl ciphers" 命令查看完整列表。
ssl_client_certificate#
指定具有受信任CA证书的PEM格式文件，用于 验证 客户端证书和OCSP响应（如果启用了 ssl_stapling）。
证书列表将发送给客户端。如果不希望如此，可以使用 ssl_trusted_certificate 指令。
ssl_conf_command#
设置任意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可能导致意外行为。
ssl_crl#
指定具有吊销证书（CRL）的PEM格式文件，用于 验证 客户端证书。
ssl_dhparam#
指定具有DHE密码的DH参数的文件。
默认情况下未设置任何参数，因此不会使用DHE密码。
ssl_early_data#
启用或禁用TLS 1.3 早期数据。
在早期数据中发送的请求可能面临 重放攻击。为防止此类攻击，应用层应使用 $ssl_early_data 变量。
proxy_set_header Early-Data $ssl_early_data;
重要
此指令在使用OpenSSL 1.1.1或更高版本以及 BoringSSL 时受支持。
ssl_ecdh_curve#
指定用于ECDHE密码的曲线。
重要
当使用OpenSSL 1.0.2或更高版本时，可以指定多个曲线，例如：
ssl_ecdh_curve prime256v1:secp384r1;
特殊值 auto 指示Angie在使用OpenSSL 1.0.2或更高版本时使用内置于OpenSSL库中的列表，或在旧版本中使用 prime256v1。
重要
当使用OpenSSL 1.0.2或更高版本时，此指令设置服务器支持的曲线列表。因此，为了使ECDSA证书正常工作，重要的是包括证书中使用的曲线。
ssl_ntls#
Added in version 1.2.0.
启用服务器端对使用 TongSuo 库的NTLS的支持。
listen ... ssl;
ssl_ntls on;
重要
使用 --with-ntls 构建选项构建Angie，并链接到启用NTLS的SSL库
./configure --with-openssl=../Tongsuo-8.3.0 \
--with-openssl-opt=enable-ntls \
--with-ntls
ssl_ocsp#
启用客户端证书链的OCSP验证。参数 leaf 仅启用客户端证书的验证。
为了使OCSP验证正常工作，必须将 ssl_verify_client 指令设置为 on 或 optional。
要解析OCSP响应者的主机名，还应该指定 resolver 指令。
示例：
ssl_verify_client on;
ssl_ocsp on;
resolver 127.0.0.53;
ssl_ocsp_cache#
设置用于OCSP验证的客户端证书状态缓存的名称和大小。缓存在所有工作进程之间共享。可以在多个虚拟服务器中使用相同名称的缓存。
参数 off 禁止使用缓存。
ssl_ocsp_responder#
覆盖在 validation 客户端证书的 "Authority Information Access" 证书扩展中指定的OCSP响应者的URI。
仅支持 "http://" OCSP响应者：
ssl_ocsp_responder http://ocsp.example.com/;
ssl_password_file#
指定包含 secret keys 的密码短语的文件，其中每个密码短语单独占一行。在加载密钥时依次尝试这些密码短语。
示例：
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;
}
}
ssl_prefer_server_ciphers#
指定在使用SSLv3和TLS协议时应优先选择服务器密码而不是客户端密码。
ssl_protocols#
|
|
默认值 |
|
http, server |
在 1.2.0 版本发生变更: TLSv1.3 参数添加到默认集合中。
启用指定的协议。
重要
仅当使用OpenSSL 1.0.1或更高版本时，TLSv1.1和TLSv1.2参数才有效。
仅当使用OpenSSL 1.1.1或更高版本时，TLSv1.3参数才有效。
ssl_reject_handshake#
如果启用，将拒绝 server 块中的 SSL 握手。
例如，在以下配置中，将拒绝与服务器名称不是 example.com 的 SSL 握手：
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;
}
ssl_session_cache#
|
|
默认值 |
|
http, server |
设置存储会话参数的缓存类型和大小。缓存可以是以下类型之一：
|
严格禁止使用会话缓存：Angie 明确告知客户端不允许重用会话。 |
|
温和禁止使用会话缓存：Angie 告知客户端可以重用会话，但实际上并不会在缓存中存储会话参数。 |
|
内建于 OpenSSL 的缓存；仅由一个工作进程使用。缓存大小以会话数指定。如果未给定大小，则默认为 20480 个会话。使用内建缓存可能导致内存碎片化。 |
|
在所有工作进程之间共享的缓存。缓存大小以字节为单位指定；一兆字节可以存储大约 4000 个会话。每个共享缓存应有一个任意名称。可以在多个虚拟服务器中使用相同名称的缓存。还用于自动生成、存储和定期轮换 TLS 会话票据密钥，除非通过 ssl_session_ticket_key 指令明确配置。 |
可以同时使用两种缓存类型，例如：
ssl_session_cache builtin:1000 shared:SSL:10m;
但仅使用共享缓存而不使用内建缓存应该更有效。
ssl_session_ticket_key#
设置用于加密和解密 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#
启用或禁用通过 TLS 会话票据 恢复会话。
ssl_session_timeout#
指定客户端可以重用会话参数的时间。
ssl_stapling#
启用或禁用服务器对 OCSP 响应的捆绑。示例：
ssl_stapling on;
resolver 127.0.0.53;
为了使 OCSP 捆绑正常工作，服务器证书颁发者的证书应该是已知的。如果 ssl_certificate 文件不包含中级证书，则服务器证书颁发者的证书应该存在于 ssl_trusted_certificate 文件中。
注意
为了解 OCSP 响应者的主机名，还应该指定 resolver 指令。
ssl_stapling_file#
设置后，捆绑的 OCSP 响应将从指定文件中获取，而不是查询服务器证书中指定的 OCSP 响应者。
文件应为 "openssl ocsp" 命令生成的 DER 格式。
ssl_stapling_responder#
覆盖 "Authority Information Access" 证书扩展中指定的 OCSP 响应者的 URI。
仅支持 "http://" OCSP 响应者：
ssl_stapling_responder http://ocsp.example.com/;
ssl_stapling_verify#
启用或禁用服务器对 OCSP 响应的验证。
为了使验证正常工作，服务器证书颁发者的证书、根证书和所有中级证书都应该配置为可信的，使用 ssl_trusted_certificate 指令。
ssl_trusted_certificate#
指定一个包含以 PEM 格式的可信 CA 证书的文件，用于 verify 客户端证书和 OCSP 响应，如果启用了 ssl_stapling。
与通过 ssl_client_certificate 设置的证书不同，这些证书列表不会发送给客户端。
ssl_verify_client#
|
|
默认值 |
|
http, server |
启用客户端证书的验证。验证结果存储在 $ssl_client_verify 变量中。
|
请求客户端证书并在证书存在时进行验证。 |
|
请求客户端证书，但不要求其由受信任的 CA 证书签署。这适用于由 Angie 外部的服务执行实际证书验证的情况。 |
ssl_verify_depth#
设置客户端证书链的验证深度。
错误处理#
http_ssl 模块支持若干非标准错误代码，可用于使用 error_page 指令进行重定向：
|
客户端证书验证期间发生错误； |
|
客户端未提供所需的证书； |
|
常规请求已发送到 HTTPS 端口。 |
重定向在请求完全解析后发生，变量如 $request_uri, $uri, $args 等可用时进行。
指定要更改的代理服务器响应头中“Set-Cookie”字段的路径属性中的文本。重定向在请求完全解析后进行，并且变量如 $request_uri, $uri, $args 和其他变量可用时进行。
内建变量#
http_ssl 模块支持内建变量：
$ssl_alpn_protocol#
返回 SSL 握手期间 ALPN 选择的协议，否则返回空字符串。
$ssl_cipher#
返回已建立 SSL 连接所使用的密码套件名称。
$ssl_ciphers#
返回客户端支持的密码套件列表。已知密码套件按名称列出，未知的以十六进制显示，例如：
AES128-SHA:AES256-SHA:0x00ff
重要
该变量仅在使用 OpenSSL 版本 1.0.2 或更高版本时完全支持。对于旧版本，该变量仅对新会话可用，并且仅列出已知密码套件。
$ssl_client_escaped_cert#
返回已建立 SSL 连接的客户端证书的 PEM 格式（URL 编码）；
$ssl_client_fingerprint#
返回已建立 SSL 连接的客户端证书的 SHA1 指纹；
$ssl_client_i_dn#
根据 RFC 2253，返回已建立 SSL 连接的客户端证书的“颁发者 DN”字符串；
$ssl_client_i_dn_legacy#
返回已建立 SSL 连接的客户端证书的“颁发者 DN”字符串。
$ssl_client_raw_cert#
返回已建立 SSL 连接的客户端证书的 PEM 格式。
$ssl_client_s_dn#
根据 RFC 2253，返回已建立 SSL 连接的客户端证书的“主体 DN”字符串。
$ssl_client_s_dn_legacy#
返回已建立 SSL 连接的客户端证书的“主体 DN”字符串。
$ssl_client_serial#
返回已建立 SSL 连接的客户端证书的序列号。
$ssl_client_v_end#
返回客户端证书的结束日期。
$ssl_client_v_remain#
返回距离客户端证书过期的天数。
$ssl_client_v_start#
返回客户端证书的开始日期。
$ssl_client_verify#
返回客户端证书验证的结果：SUCCESS, "FAILED:reason", 如果没有证书则返回 NONE。
$ssl_curve#
返回用于 SSL 握手密钥交换过程的协商曲线。已知曲线按名称列出，未知的以十六进制显示，例如：
prime256v1
重要
该变量仅在使用 OpenSSL 版本 3.0 或更高版本时支持。对于旧版本，变量值将是空字符串。
$ssl_curves#
返回客户端支持的曲线列表。已知曲线按名称列出，未知的以十六进制显示，例如：
0x001d:prime256v1:secp521r1:secp384r1
重要
该变量仅在使用 OpenSSL 版本 1.0.2 或更高版本时支持。对于旧版本，变量值将是空字符串。
该变量仅对新会话可用。
$ssl_early_data#
如果使用 TLS 1.3 early 数据且握手未完成，返回“1”，否则返回“”。
$ssl_protocol#
返回已建立 SSL 连接的协议。
$ssl_server_cert_type#
根据服务器证书和密钥的类型，取值为 RSA, DSA, ECDSA, ED448, ED25519, SM2, RSA-PSS, 或 unknown。
$ssl_server_name#
返回通过 SNI 请求的服务器名称；
$ssl_session_id#
返回已建立 SSL 连接的会话标识符。
$ssl_session_reused#
如果重复使用 SSL 会话，返回 r，否则返回“.”。