SSL#
提供流代理服务器与 SSL/TLS 协议一起工作的必要支持。
当从源码 构建 时，此模块默认未构建；应该使用 --with-stream_ssl_module 构建选项 启用。
在来自 我们的仓库 的包和镜像中，模块已包含在构建中。
重要
此模块需要 OpenSSL 库。
配置示例#
为了减少处理器负载，建议
worker_processes auto;
stream {
#...
server {
listen 12345 ssl;
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_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 的值，从而从变量中加载证书而无需使用中间文件。
请注意，不当使用此语法可能会产生安全隐患，例如将秘密密钥数据写入 错误日志。
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 引擎 name 中加载具有指定 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#
指定用于 验证 客户端证书的 PEM 格式的受信 CA 证书文件。
证书列表将发送给客户端。如果不希望这样，可以使用 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_ecdh_curve#
指定用于 ECDHE 密码的曲线。
重要
使用 OpenSSL 1.0.2 或更高版本时，可以指定多个曲线，例如：
ssl_ecdh_curve prime256v1:secp384r1;
特殊值 auto 指示 Angie 使用 OpenSSL 库内置列表（使用 OpenSSL 1.0.2 或更高版本时）或使用旧版本的 prime256v1。
重要
使用 OpenSSL 1.0.2 或更高版本时，此指令设置服务器支持的曲线列表。因此，为了使 ECDSA 证书正常工作，重要的是包括证书中使用的曲线。
ssl_handshake_timeout#
指定 SSL 握手完成的超时时间。
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_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 个会话。每个共享缓存应有一个任意名称。具有相同名称的缓存可用于多个服务器中。除非使用 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_trusted_certificate#
指定一个包含受信任 CA 证书的文件，格式为 PEM，用于 验证 客户端证书。
与 ssl_client_certificate 设置的证书不同，这些证书列表不会发送给客户端。
ssl_verify_client#
|
|
默认值 |
|
stream, server |
启用客户端证书的验证。验证结果存储在 $ssl_client_verify 变量中。如果在客户端证书验证期间发生错误或客户端未提供所需的证书，则连接将关闭。
|
请求客户端证书并在证书存在时进行验证。 |
|
请求客户端证书，但不要求其由受信任的 CA 证书签名。这适用于 Angie 之外的服务执行实际证书验证的情况。 |
ssl_verify_depth#
设置客户端证书链的验证深度。
内建变量#
stream_ssl 模块支持以下变量：
$ssl_alpn_protocol#
返回在 SSL 握手期间通过 ALPN 选择的协议，否则返回空字符串。
$ssl_cipher#
返回已建立 SSL 连接使用的密码名称。
$ssl_ciphers#
返回客户端支持的密码列表。已知密码按名称列出，未知密码以十六进制显示，例如：
AES128-SHA:AES256-SHA:0x00ff
重要
该变量仅在使用 OpenSSL 1.0.2 或更高版本时完全支持。在较旧版本中，该变量仅适用于新会话，并且仅列出已知密码。
$ssl_client_cert#
返回已建立 SSL 连接的客户端证书，格式为 PEM，每行（除第一行外）前面加制表符。
$ssl_client_fingerprint#
返回已建立 SSL 连接的客户端证书的 SHA1 指纹。
$ssl_client_i_dn#
返回已建立 SSL 连接的客户端证书的“颁发者 DN”字符串，依据 RFC 2253。
$ssl_client_raw_cert#
返回已建立 SSL 连接的客户端证书，格式为 PEM。
$ssl_client_s_dn#
返回已建立 SSL 连接的客户端证书的“主题 DN”字符串，依据 RFC 2253。
$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_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#
返回 r 如果 SSL 会话被重用，否则返回 "."