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— 定义元素在此时间内未被访问即会被移除的时长，即使其仍处于valid周期内；每次访问都会重置此计时器。默认为 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_compression#
启用 TLS 1.3 服务器证书 压缩。
备注
在使用 OpenSSL 3.2 或更高版本时支持该指令;支持的压缩算法列表由库提供。
备注
在使用 BoringSSL 时支持该指令;支持的压缩算法列表包括 zlib。
如果启用了 ssl_stapling,则禁用证书压缩。
ssl_certificate_key#
为给定的虚拟服务器指定 PEM 格式的私钥文件。
备注
使用 OpenSSL 1.0.2 或更高版本时,可以在文件名中使用变量。
可以指定值 engine:name:id 来代替 file,这将从 OpenSSL 引擎 name 加载具有指定 id 的私钥。
可以指定值 store:scheme:id 来代替 file,用于从具有指定 id 和 OpenSSL 提供程序注册的 URI scheme 加载私钥,例如 pkcs11。
可以指定值 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_encrypted_hello_key#
Added in version 1.11.0.
指定一个包含 PEM 格式的 ECH 私钥和 ECHConfigList 的文件。 该指令可以指定多次。 需要支持加密客户端问候 (ECH) 的 OpenSSL 或 BoringSSL 构建; 否则不支持。
ssl_keylog_file#
Added in version 1.12.0.
指定一个文件，用于记录由该上下文处理的连接的 SSL/TLS 密钥，采用 SSLKEYLOGFILE 格式，Wireshark 等工具使用该格式来解密捕获的 TLS 流量。
该指令不应与 LibreSSL 一起使用。
警告
该文件包含敏感的 TLS 密钥材料，可用于解密相应连接的已捕获流量。 请仅将该指令用于调试或协议分析，限制对该文件的访问，并在不再需要时将其删除。
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 验证正常工作,:ref: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 |
启用指定的协议。
备注
TLSv1.1 和 TLSv1.2 参数仅在使用 OpenSSL 1.0.1 或更高版本时有效。
TLSv1.3 参数仅在使用 OpenSSL 1.1.1 或更高版本时有效。
ssl_reject_handshake#
如果启用,:ref: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_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_sigalg#
返回已建立的 SSL 连接的客户端证书的`签名算法 <https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-16>`_。
备注
仅在使用 OpenSSL 3.5 或更高版本时才支持该变量。对于较旧版本，该变量值将为空字符串。
备注
该变量仅适用于新会话。
$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 早期数据 且握手未完成，则返回"1"，否则返回""。
$ssl_encrypted_hello#
Added in version 1.11.0.
如果使用加密客户端问候（ECH），则返回"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"，否则返回"."。
$ssl_sigalg#
返回已建立的 SSL 连接的服务器证书的`签名算法 <https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-16>`_。
备注
仅在使用 OpenSSL 3.5 或更高版本时才支持该变量。对于较旧版本，该变量值将为空字符串。
备注
该变量仅适用于新会话。
$ssl_sigalgs#
返回客户端在 SSL 握手期间提供的 签名算法 列表，以冒号分隔。
备注
对于 OpenSSL 4.0 或更高版本，算法以名称形式返回；没有名称的算法回退为其原始十六进制代码。暴露旧版签名算法 API 的 SSL 库将所有算法作为原始十六进制代码返回。不支持签名算法 API 的构建返回空值。
目录