SSL#
提供 HTTPS 所需的支持。
当 从源代码构建 时，此模块默认并未构建；应通过 ‑‑with‑http_ssl_module 构建选项 启用。
在 我们的仓库 中的包和映像中，该模块包含在构建中。
重要
此模块需要 OpenSSL 库。
配置示例#
为了降低处理器负载，建议
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，这会从变量中加载证书，而无需使用中间文件。请注意，不当使用此语法可能会带来安全隐患，例如将私钥数据写入 错误日志。
重要
需要记住的是，由于 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 版本。可以使用 openssl ciphers 命令查看完整列表。
ssl_client_certificate#
指定用于 验证 客户端证书和 OCSP 响应的 PEM 格式受信任 CA 证书文件，如果启用了 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#
指定用于 验证 客户端证书的 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 指示 Angie 在使用 OpenSSL 1.0.2 或更高版本时使用 OpenSSL 库内置的列表，或者在较旧版本中使用 prime256v1。
重要
在使用 OpenSSL 1.0.2 或更高版本时，该指令设置服务器支持的曲线列表。因此，为了使 ECDSA 证书能够正常工作，重要的是要包括证书中使用的曲线。
ssl_ntls#
Added in version 1.2.0.
启用服务器端对 NTLS 的支持，使用 TongSuo 库。
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 验证。:samp:`leaf 参数仅启用客户端证书的验证。
为了使 OCSP 验证正常工作，ssl_verify_client 指令应设置为 :samp:`on 或 :samp:`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#
如果启用，: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 会话。使用内置缓存可能导致内存碎片。 |
| 在所有工作进程之间共享的缓存。缓存大小以字节为单位指定；一兆字节可以存储大约 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 响应的 stapling。示例：
ssl_stapling on;
resolver 127.0.0.53;
为了使 OCSP stapling 生效，服务器证书颁发者的证书应为已知。如果 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#
指定用于 验证 客户端证书和 OCSP 响应的 PEM 格式的受信任 CA 证书文件，如果启用了 ssl_stapling。
与 ssl_client_certificate 设置的证书不同，这些证书的列表不会发送给客户端。
ssl_verify_client#
启用客户端证书的验证。验证结果存储在 $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 选择的协议，否则返回空字符串。 返回用于建立 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 early 数据且握手尚未完成，则返回 "1"，否则返回 ""。 返回已建立 SSL 连接的协议。 根据服务器证书和密钥的类型，取值 返回通过 SNI 请求的服务器名称； 返回已建立 SSL 连接的会话标识符。 如果 SSL 会话被重用，则返回 $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#r，否则返回 "."。