SSL#
提供 HTTPS 所需的支持。
当从 源代码构建 时,
此模块默认不会被构建;
应使用
‑‑with‑http_ssl_module
构建选项 启用。
在来自 我们仓库 的软件包和镜像中, 该模块已包含在构建中。
备注
此模块需要 OpenSSL 库。
配置示例#
为了降低处理器负载,建议
将 工作进程 数量设置为等于处理器数量,
启用 keep-alive 连接,
启用 共享 会话缓存,
禁用 内置 会话缓存,
并可能增加会话 生命周期 (默认为 5 分钟):
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;
# ...
}
指令#
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,这将从变量加载证书而不使用中间文件。请注意,不当使用此语法可能会带来安全隐患,例如将私钥数据写入 错误日志。
ssl_certificate_cache#
| |
默认值 |
|
http, server |
定义一个缓存,用于存储使用变量指定的 SSL 证书 和 私钥。
该指令支持以下参数:
max— 设置缓存中的最大元素数量。当缓存溢出时, 最近最少使用 (LRU) 的元素将被移除。inactive— 定义元素在未被访问的情况下被移除的时间。 默认为 10 秒。valid— 定义缓存元素被视为有效并可以重用的时间。 默认为 60 秒。在此期间之后, 证书将被重新加载或重新验证。off— 禁用缓存。
示例:
ssl_certificate $ssl_server_name.crt;
ssl_certificate_key $ssl_server_name.key;
ssl_certificate_cache max=1000 inactive=20s valid=1m;
ssl_certificate_key#
为给定的虚拟服务器指定 PEM 格式的私钥文件。
备注
使用 OpenSSL 1.0.2 或更高版本时,可以在文件名中使用变量。
可以指定值 engine:name:id 来代替 file,这将从 OpenSSL 引擎 name 加载具有指定 id 的私钥。
可以指定值 data:$variable 来代替 file,这将从变量加载私钥而不使用中间文件。请注意,不当使用此语法可能会带来安全隐患,例如将私钥数据写入 错误日志。
如果启用了 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_key rsa.key;
ssl_ciphers#
指定启用的密码套件。密码套件以 OpenSSL 库理解的格式指定,例如:
ssl_ciphers ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;
密码套件列表取决于安装的 OpenSSL 版本。
可以使用 openssl ciphers 命令查看完整列表。
警告
使用 OpenSSL 时,:samp:ssl_ciphers 指令 不 配置 TLS 1.3 的密码套件。要使用 OpenSSL 配置 TLS 1.3 密码套件,请使用 ssl_conf_command 指令,该指令是为支持高级 SSL 配置而添加的。
在 LibreSSL 中,TLS 1.3 密码套件 可以 使用
ssl_ciphers配置。在 BoringSSL 中,TLS 1.3 密码套件根本无法配置。
ssl_client_certificate#
指定 PEM 格式的受信任 CA 证书文件,用于 验证 客户端证书,以及在启用 ssl_stapling 时验证 OCSP 响应。
证书列表将发送给客户端。如果不希望这样做,可以使用 ssl_trusted_certificate 指令。
ssl_conf_command#
设置任意 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#
指定用于 验证 客户端证书的 PEM 格式吊销证书文件（CRL）。
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 对应于 OpenSSL 1.0.2 或更高版本中 OpenSSL 库内置的曲线列表，或者在较旧版本中对应于 prime256v1。
备注
在使用 OpenSSL 1.0.2 或更高版本时，该指令设置服务器支持的曲线列表。因此，为了使 ECDSA 证书能够正常工作，重要的是要包括证书中使用的曲线。
ssl_ntls#
在使用 TongSuo TLS 库时启用服务器端对 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#
覆盖在 "Authority Information Access" 证书扩展中指定的 OCSP 响应者的 URI，用于 验证 客户端证书。
仅支持 http:// OCSP 响应者：
ssl_ocsp_responder http://ocsp.example.com/;
ssl_password_file#
指定一个包含 私钥 密码短语的文件，每个密码短语在单独的一行中指定。加载密钥时将依次尝试密码短语。
示例：
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 参数被添加到默认集合中。
启用指定的协议。
备注
TLSv1.1 和 TLSv1.2 参数仅在使用 OpenSSL 1.0.1 或更高版本时有效。
TLSv1.3 参数仅在使用 OpenSSL 1.1.1 或更高版本时有效。
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 个会话。使用内置缓存可能导致内存碎片。 |
| 在所有工作进程之间共享的缓存。缓存大小以字节指定;1 兆字节可以存储约 4000 个会话。每个共享缓存应有一个任意名称。具有相同名称的缓存可以在多个虚拟服务器中使用。除非使用 ssl_session_ticket_key 指令显式配置,否则它还用于自动生成、存储和定期轮换 TLS 会话票证密钥。 |
两种缓存类型可以同时使用,例如:
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 响应者。
该文件应为 DER 格式,由 openssl ocsp 命令生成。
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 证书的文件,用于 验证 客户端证书,以及在启用 ssl_stapling 时验证 OCSP 响应。
与 ssl_client_certificate 设置的证书集不同,这些证书的列表不会发送给客户端。
ssl_verify_client#
启用客户端证书验证。验证结果存储在 $ssl_client_verify 变量中。
| 请求客户端证书,如果证书存在则进行验证。 |
| 请求客户端证书,但不要求其由受信任的 CA 证书签名。这适用于由 Angie 外部的服务执行实际证书验证的情况。 |
ssl_verify_depth#
设置客户端证书链中的验证深度。
错误处理#
http_ssl 模块支持几个非标准错误代码，可以使用 error_page 指令进行重定向：
| 客户端证书验证过程中发生错误； |
| 客户端未提供所需的证书； |
| 常规请求已发送到 HTTPS 端口。 |
重定向发生在请求完全解析之后，此时变量（如 $request_uri、$uri、$args 等）已可用。
内置变量#
http_ssl 模块支持内置变量： 返回在 SSL 握手期间通过 ALPN 选择的协议，否则返回空字符串。 返回已建立的 SSL 连接所使用的密码套件名称。 返回客户端支持的密码套件列表。已知的密码套件按名称列出，未知的以十六进制显示，例如： AES128-SHA:AES256-SHA:0x00ff 备注 仅在使用 OpenSSL 1.0.2 或更高版本时才完全支持该变量。对于较旧版本，该变量仅适用于新会话，并且仅列出已知的密码套件。 返回已建立的 SSL 连接的 PEM 格式客户端证书（URL 编码）。 返回已建立的 SSL 连接的客户端证书的 SHA1 指纹。 根据 RFC 2253 返回已建立的 SSL 连接的客户端证书的"颁发者 DN"字符串。 返回已建立的 SSL 连接的客户端证书的"颁发者 DN"字符串。 返回已建立的 SSL 连接的 PEM 格式客户端证书。 根据 RFC 2253 返回已建立的 SSL 连接的客户端证书的"主题 DN"字符串。 返回已建立的 SSL 连接的客户端证书的"主题 DN"字符串。 返回已建立的 SSL 连接的客户端证书的序列号。 返回客户端证书的结束日期。 返回客户端证书到期前的剩余天数。 返回客户端证书的开始日期。 返回客户端证书验证的结果： 返回在 SSL 握手期间用于密钥交换的协商曲线。已知的曲线按名称列出，未知的以十六进制显示，例如： prime256v1 备注 仅在使用 OpenSSL 3.0 或更高版本时才支持该变量。对于较旧版本，该变量值将为空字符串。 返回客户端支持的曲线列表。已知的曲线按名称列出，未知的以十六进制显示，例如： 0x001d:prime256v1:secp521r1:secp384r1 备注 仅在使用 OpenSSL 1.0.2 或更高版本时才支持该变量。对于较旧版本，该变量值将为空字符串。 该变量仅适用于新会话。 如果使用 TLS 1.3 早期数据 且握手未完成，则返回"1"，否则返回""。 返回已建立的 SSL 连接的协议。 根据服务器证书和密钥的类型，取值为 返回通过 SNI 请求的服务器名称。 返回已建立的 SSL 连接的会话标识符。 如果 SSL 会话被重用，则返回"r"，否则返回"."。$ssl_alpn_protocol#$ssl_cipher#$ssl_ciphers#$ssl_client_escaped_cert#$ssl_client_fingerprint#$ssl_client_i_dn#$ssl_client_i_dn_legacy#$ssl_client_raw_cert#$ssl_client_s_dn#$ssl_client_s_dn_legacy#$ssl_client_serial#$ssl_client_v_end#$ssl_client_v_remain#$ssl_client_v_start#$ssl_client_verify#SUCCESS、FAILED:reason，如果未提供证书则返回 NONE。$ssl_curve#$ssl_curves#$ssl_early_data#$ssl_protocol#$ssl_server_cert_type#RSA、DSA、ECDSA、ED448、
ED25519、SM2、RSA-PSS 或 unknown。$ssl_server_name#$ssl_session_id#$ssl_session_reused#
目录