SSL#

提供了流代理服务器与SSL/TLS协议配合工作的必要支持。

从源代码构建 时, 此模块默认不构建; 应使用 --with-stream_ssl_module 构建选项 启用它。

我们的仓库 中的包和镜像中, 该模块包含在构建中。

重要

此模块需要OpenSSL库。

配置示例#

为了减少处理器负载,建议

  • 工作进程 的数量设置为处理器的数量,

  • 启用 共享 会话缓存,

  • 禁用 内置 会话缓存,

  • 并可能增加会话的 生命周期 (默认值为5分钟):

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#

语法

ssl_alpn protocol ...;

默认

上下文

stream, server

指定支持的 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#

语法

ssl_certificate file [file];

默认

上下文

stream, server

指定给定服务器的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;

# dual NTLS certificate
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#

语法

ssl_certificate_key file [file];

默认

上下文

stream, server

指定给定服务器的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;

# dual NTLS certificate
ssl_certificate      sign.crt enc.crt;
ssl_certificate_key  sign.key enc.key;

# 可以与常规RSA证书结合使用:
ssl_certificate  rsa.crt;
ssl_certificate  rsa.key;

ssl_ciphers#

语法

ssl_ciphers ciphers;

默认

ssl_ciphers HIGH:!aNULL:!MD5;

上下文

stream, server

指定启用的密码。密码以OpenSSL库理解的格式指定,例如:

ssl_ciphers ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;

密码列表取决于已安装的 OpenSSL 版本。可以使用 openssl ciphers 命令查看完整列表。

ssl_client_certificate#

语法

ssl_client_certificate file;

默认

上下文

stream, server

指定用于 验证 客户端证书和OCSP响应的PEM格式的受信任CA证书文件,如果 ssl_stapling 被启用。

证书列表将发送给客户端。如果不希望这样,可以使用 ssl_trusted_certificate 指令。

ssl_conf_command#

语法

ssl_conf_command name value;

默认

上下文

stream, server

设置任意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#

语法

ssl_crl file;

默认

上下文

stream, server

指定PEM格式的被吊销证书文件(CRL),用于 验证 客户端证书。

ssl_dhparam#

语法

ssl_dhparam file;

默认

上下文

stream, server

指定用于DHE密码的DH参数文件。

小心

默认情况下未设置任何参数,因此不会使用DHE密码。

ssl_ecdh_curve#

语法

ssl_ecdh_curve curve;

默认

ssl_ecdh_curve auto;

上下文

stream, server

指定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_handshake_timeout time;

默认

ssl_handshake_timeout 60s;

上下文

stream, server

指定SSL握手完成的超时时间。

ssl_ocsp#

语法

ssl_ocsp on | off | leaf;

默认

ssl_ocsp off;

上下文

http, server

启用客户端证书链的OCSP验证。 leaf 参数仅启用客户端证书的验证。

为了使OCSP验证工作, ssl_verify_client 指令应设置为 onoptional

为了解析OCSP响应者主机名,还应指定 resolver 指令。

示例:

ssl_verify_client on;
ssl_ocsp          on;
resolver          127.0.0.53;

ssl_ocsp_cache#

语法

ssl_ocsp_cache off | [shared:name:size];

默认

ssl_ocsp_cache off;

上下文

http, server

设置存储客户端证书状态以进行OCSP验证的缓存的名称和大小。该缓存在所有工作进程之间共享。可以在多个虚拟服务器中使用具有相同名称的缓存。

off 参数禁止使用缓存。

ssl_ocsp_responder#

语法

ssl_ocsp_responder uri;

默认

上下文

http, server

覆盖在 validation 客户端证书验证中指定的 "Authority Information Access" 证书扩展的 OCSP 响应者 URI。

仅支持 http:// OCSP 响应者:

ssl_ocsp_responder http://ocsp.example.com/;

ssl_ntls#

Added in version 1.2.0.

Syntax

ssl_ntls on | off;

Default

ssl_ntls off;

Context

stream, server

启用使用 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#

Syntax

ssl_password_file file;

Default

Context

stream, server

指定一个包含 secret keys 密码的文件,每个密码在单独的一行上。加载密钥时,依次尝试这些密码。

示例:

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#

Syntax

ssl_prefer_server_ciphers on | off;

Default

ssl_prefer_server_ciphers off;

Context

stream, server

指定在使用 SSLv3 和 TLS 协议时应优先使用服务器密码而不是客户端密码。

ssl_protocols#

Syntax

ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];

默认值

ssl_protocols TLSv1.2 TLSv1.3;

上下文

stream, server

在 1.2.0 版本发生变更: TLSv1.3 参数已添加到默认集合。

启用指定的协议。

重要

TLSv1.1 和 TLSv1.2 参数仅在使用 OpenSSL 1.0.1 或更高版本时有效。

TLSv1.3 参数仅在使用 OpenSSL 1.1.1 或更高版本时有效。

ssl_session_cache#

Syntax

ssl_session_cache off | none | [builtin[:size]] [shared:name:size];

Default

ssl_session_cache none;

Context

stream, server

设置存储会话参数的缓存类型和大小。缓存可以是以下类型之一:

off

严格禁止使用会话缓存:Angie 明确告诉客户端会话不能被重用。

none

温和地不允许使用会话缓存:Angie 告诉客户端会话可以重用,但实际上不在缓存中存储会话参数。

builtin

OpenSSL 内置的缓存;仅由一个工作进程使用。缓存大小以会话为单位指定。如果未给定大小,则等于 20480 会话。使用内置缓存可能会导致内存碎片。

shared

在所有工作进程之间共享的缓存。缓存大小以字节为单位指定;一兆字节大约可以存储 4000 会话。每个共享缓存应具有任意名称。具有相同名称的缓存可以在多个服务器中使用。它还用于自动生成、存储和定期轮换 TLS 会话票据密钥,除非使用 ssl_session_ticket_key 指令明确配置。

可以同时使用两种缓存类型,例如:

ssl_session_cache builtin:1000 shared:SSL:10m;

但仅使用共享缓存而不使用内置缓存应更有效。

ssl_session_ticket_key#

Syntax

ssl_session_ticket_key file;

Default

Context

stream, server

设置用于加密和解密 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#

Syntax

ssl_session_tickets on | off;

Default

ssl_session_tickets on;

Context

stream, server

启用或禁用通过 TLS 会话票据 的会话恢复。

ssl_session_timeout#

Syntax

ssl_session_timeout time;

Default

ssl_session_timeout 5m;

Context

stream, server

指定客户端可以重用会话参数的时间。

ssl_stapling#

Syntax

ssl_stapling on | off;

Default

ssl_stapling off;

Context

http, server

启用或禁用服务器的 OCSP 响应 stapling。 示例:

ssl_stapling on;
resolver 127.0.0.53;

为了使 OCSP stapling 工作,服务器证书颁发者的证书应是已知的。如果 ssl_certificate 文件不包含中间证书,则服务器证书颁发者的证书应存在于 ssl_trusted_certificate 文件中。

注意

对于 OCSP 响应者主机名的解析,还应指定 resolver 指令。

ssl_stapling_file#

Syntax

ssl_stapling_file file;

Default

Context

http, server

设置时,粘贴的 OCSP 响应将来自指定文件,而不是查询服务器证书中指定的 OCSP 响应者。

该文件应为 DER 格式,由 openssl ocsp 命令生成。

ssl_stapling_responder#

Syntax

ssl_stapling_responder uri;

Default

Context

http, server

覆盖在 "Authority Information Access" 证书扩展中指定的 OCSP 响应者 URI。

仅支持 http:// OCSP 响应者:

ssl_stapling_responder http://ocsp.example.com/;

ssl_stapling_verify#

Syntax

ssl_stapling_verify on | off;

Default

ssl_stapling_verify off;

Context

http, server

启用或禁用服务器对 OCSP 响应的验证。

为了使验证工作,服务器证书颁发者的证书、根证书和所有中间证书应使用 ssl_trusted_certificate 指令配置为信任。

ssl_trusted_certificate#

Syntax

ssl_trusted_certificate file;

Default

Context

stream, server

指定一个包含 PEM 格式的受信任 CA 证书的文件,用于 verify 客户端证书。

ssl_client_certificate 指定的证书相比,这些证书的列表不会发送给客户端。

ssl_verify_client#

Syntax

ssl_verify_client on | off | optional | optional_no_ca;

Default

ssl_verify_client off;

Context

stream, server

启用客户端证书的验证。验证结果存储在 $ssl_client_verify 变量中。如果在客户端证书验证过程中发生错误,或者客户端未提供所需证书,则连接将关闭。

optional

请求客户端证书,并在证书存在时进行验证。

optional_no_ca

请求客户端证书,但不要求其由受信任的 CA 证书签名。这适用于 Angie 外部的服务执行实际证书验证的情况。

ssl_verify_depth#

语法

ssl_verify_depth 数字;

默认

ssl_verify_depth 1;

上下文

stream, server

设置客户端证书链的验证深度。

内置变量#

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#

根据服务器证书和密钥的类型,取值为 RSADSAECDSAED448ED25519SM2RSA-PSSunknown

$ssl_server_name#

返回通过 SNI 请求的服务器名称。

$ssl_session_id#

返回已建立SSL连接的会话标识符。

$ssl_session_reused#

如果SSL会话被重用,则返回 r,否则返回 "."。