SSL#
为流代理服务器提供使用 SSL/TLS 协议所需的支持。
当 从源代码构建 时,
此模块默认不会被构建;
应该使用
--with-stream_ssl_module
构建选项 来启用它。
在来自 我们仓库 的软件包和镜像中, 此模块已包含在构建中。
备注
此模块需要 OpenSSL 库。
配置示例#
为了降低处理器负载,建议
worker_processes auto;
stream {
#...
server {
listen 12345 ssl;
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_alpn#
指定支持的 ALPN 协议列表。如果客户端使用 ALPN,则必须 协商 其中一个协议:
map $ssl_alpn_protocol $proxy {
h2 127.0.0.1:8001;
http/1.1 127.0.0.1:8002;
}
server {
listen 12346;
proxy_pass $proxy;
ssl_alpn h2 http/1.1;
}
ssl_certificate#
为给定服务器指定一个包含 PEM 格式证书的文件。如果除了主证书之外还需要指定中间证书,则应该按以下顺序在同一文件中指定它们:首先是主证书,然后是中间证书。PEM 格式的密钥可以放在同一文件中。
此指令可以多次指定以加载不同类型的证书,例如 RSA 和 ECDSA:
server {
listen 12345 ssl;
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_key#
为给定服务器指定一个包含 PEM 格式密钥的文件。
备注
使用 OpenSSL 1.0.2 或更高版本时,可以在文件名中使用变量。
可以指定值 engine:`name`:id 来代替 file,这会从名为 name 的 OpenSSL 引擎加载具有指定 id 的密钥。
可以指定值 data:`$variable` 来代替 file,这会从变量加载密钥而不使用中间文件。请注意,不当使用此语法可能会带来安全隐患,例如将密钥数据写入 错误日志。
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 早期数据。
备注
使用 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_handshake_timeout#
指定 SSL 握手完成的超时时间。
ssl_ocsp#
启用客户端证书链的 OCSP 验证。leaf 参数仅启用客户端证书的验证。
要使 OCSP 验证正常工作,:ref:s_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_ntls#
使用 TongSuo 库启用服务器端 NTLS 支持。
listen ... ssl;
ssl_ntls on;
备注
Angie 必须使用 --with-ntls 构建选项进行构建，并链接到启用 NTLS 的 SSL 库
./configure --with-openssl=../Tongsuo-8.3.0 \
--with-openssl-opt=enable-ntls \
--with-ntls
ssl_password_file#
指定包含 私钥 密码短语的文件，其中每个密码短语单独占一行。加载密钥时依次尝试这些密码短语。
示例：
stream {
ssl_password_file /etc/keys/global.pass;
...
server {
listen 127.0.0.1:12345;
ssl_certificate_key /etc/keys/first.key;
}
server {
listen 127.0.0.1:12346;
# 也可以使用命名管道代替文件
ssl_password_file /etc/keys/fifo;
ssl_certificate_key /etc/keys/second.key;
}
}
ssl_prefer_server_ciphers#
指定在使用 SSLv3 和 TLS 协议时，服务器密码应优先于客户端密码。
ssl_protocols#
| |
默认值 |
|
stream, server |
在 1.2.0 版本发生变更: TLSv1.3 参数已添加到默认集合。
启用指定的协议。
备注
TLSv1.1 和 TLSv1.2 参数仅在使用 OpenSSL 1.0.1 或更高版本时有效。
TLSv1.3 参数仅在使用 OpenSSL 1.1.1 或更高版本时有效。
ssl_session_cache#
| |
默认值 |
|
stream, 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 响应器。
该文件应该是 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_client_certificate 设置的证书集不同，这些证书列表不会发送给客户端。
ssl_verify_client#
启用客户端证书验证。验证结果存储在 $ssl_client_verify 变量中。如果在客户端证书验证期间发生错误，或者客户端未提供所需的证书，则连接将被关闭。
| 请求客户端证书，如果证书存在则进行验证。 |
| 请求客户端证书，但不要求其由受信任的 CA 证书签名。这适用于由 Angie 外部的服务执行实际证书验证的情况。 |
ssl_verify_depth#
设置客户端证书链中的验证深度。
内置变量#
返回在 SSL 握手期间通过 ALPN 选择的协议，否则返回空字符串。 返回已建立的 SSL 连接所使用的加密套件名称。 返回客户端支持的加密套件列表。已知的加密套件以名称列出，未知的以十六进制显示，例如： AES128-SHA:AES256-SHA:0x00ff 备注 仅在使用 OpenSSL 1.0.2 或更高版本时完全支持该变量。对于旧版本，该变量仅适用于新会话，并且仅列出已知的加密套件。 返回已建立的 SSL 连接的客户端证书（PEM 格式），除第一行外的每一行都以制表符开头。 返回已建立的 SSL 连接的客户端证书的 SHA1 指纹。 根据 RFC 2253 返回已建立的 SSL 连接的客户端证书的"颁发者 DN"字符串。 返回已建立的 SSL 连接的客户端证书（PEM 格式）。 根据 RFC 2253 返回已建立的 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"，否则返回 "."。stream_ssl 模块支持以下变量：$ssl_alpn_protocol#$ssl_cipher#$ssl_ciphers#$ssl_client_cert#$ssl_client_fingerprint#$ssl_client_i_dn#$ssl_client_raw_cert#$ssl_client_s_dn#$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#
目录