SSL#

提供必要的HTTPS支持。

当从 源代码构建 时, 此模块默认未构建; 可以通过使用 ‑‑with‑http_ssl_module 构建选项 来启用它。

在来自 我们仓库 的软件包和镜像中, 该模块已包含在构建中。

重要

此模块需要OpenSSL库。

配置示例#

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

worker_processes auto;

http {

    # ...

    server {
        listen              443 ssl;
        keepalive_timeout   70;

        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_buffer_size#

语法

ssl_buffer_size size;

默认值

ssl_buffer_size 16k;

上下文

http, server

设置用于发送数据的缓冲区大小。

默认情况下,缓冲区大小为16k,这在发送大响应时对应于最小开销。为了最小化首字节时间,可以使用较小的值,例如:

ssl_buffer_size 4k;

ssl_certificate#

语法

ssl_certificate file [file];

默认值

上下文

http, server

指定具有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#

语法

ssl_certificate_key file [file];

默认值

上下文

http, server

指定具有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#

语法

ssl_ciphers ciphers;

默认值

ssl_ciphers HIGH:!aNULL:!MD5;

上下文

http, server

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

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

可以使用 "openssl ciphers" 命令查看完整列表。

ssl_client_certificate#

语法

ssl_client_certificate file;

默认值

上下文

http, server

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

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

ssl_conf_command#

语法

ssl_conf_command name value;

默认值

上下文

http, 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;

默认值

上下文

http, server

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

ssl_dhparam#

语法

ssl_dhparam file;

默认值

上下文

http, server

指定具有DHE密码的DH参数的文件。

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

ssl_early_data#

语法

ssl_early_data on | off;

默认值

ssl_early_data off;

上下文

http, server

启用或禁用TLS 1.3 早期数据

在早期数据中发送的请求可能面临 重放攻击。为防止此类攻击,应用层应使用 $ssl_early_data 变量。

proxy_set_header Early-Data $ssl_early_data;

重要

此指令在使用OpenSSL 1.1.1或更高版本以及 BoringSSL 时受支持。

ssl_ecdh_curve#

语法

ssl_ecdh_curve curve;

默认值

ssl_ecdh_curve auto;

上下文

http, 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_ntls#

Added in version 1.2.0.

语法

ssl_ntls on | off;

默认值

ssl_ntls off;

上下文

http, 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_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_password_file#

语法

ssl_password_file file;

默认值

上下文

http, server

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

示例:

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#

语法

ssl_prefer_server_ciphers on | off;

默认值

ssl_prefer_server_ciphers off;

上下文

http, server

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

ssl_protocols#

语法

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

默认值

ssl_protocols TLSv1 TLSv1.1 TLSv1.2 TLSv1.3;

上下文

http, server

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

启用指定的协议。

重要

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

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

ssl_reject_handshake#

语法

ssl_reject_handshake on | off;

默认值

ssl_reject_handshake off;

上下文

http, server

如果启用,将拒绝 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#

语法

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

默认值

ssl_session_cache none;

上下文

http, 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#

语法

ssl_session_ticket_key file;

默认值

上下文

http, 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#

语法

ssl_session_tickets on | off;

默认值

ssl_session_tickets on;

上下文

http, server

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

ssl_session_timeout#

语法

ssl_session_timeout time;

默认值

ssl_session_timeout 5m;

上下文

http, server

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

ssl_stapling#

语法

ssl_stapling on | off;

默认值

ssl_stapling off;

上下文

http, server

启用或禁用服务器对 OCSP 响应的捆绑。示例:

ssl_stapling on;
resolver 127.0.0.53;

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

注意

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

ssl_stapling_file#

语法

ssl_stapling_file file;

默认值

上下文

http, server

设置后,捆绑的 OCSP 响应将从指定文件中获取,而不是查询服务器证书中指定的 OCSP 响应者。

文件应为 "openssl ocsp" 命令生成的 DER 格式。

ssl_stapling_responder#

语法

ssl_stapling_responder uri;

默认值

上下文

http, server

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

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

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

ssl_stapling_verify#

语法

ssl_stapling_verify on | off;

默认值

ssl_stapling_verify off;

上下文

http, server

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

为了使验证正常工作,服务器证书颁发者的证书、根证书和所有中级证书都应该配置为可信的,使用 ssl_trusted_certificate 指令。

ssl_trusted_certificate#

语法

ssl_trusted_certificate file;

默认值

上下文

http, server

指定一个包含以 PEM 格式的可信 CA 证书的文件,用于 verify 客户端证书和 OCSP 响应,如果启用了 ssl_stapling

与通过 ssl_client_certificate 设置的证书不同,这些证书列表不会发送给客户端。

ssl_verify_client#

语法

ssl_verify_client on | off | optional | optional_no_ca;

默认值

ssl_verify_client off;

上下文

http, server

启用客户端证书的验证。验证结果存储在 $ssl_client_verify 变量中。

optional

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

optional_no_ca

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

ssl_verify_depth#

语法

ssl_verify_depth number;

默认值

ssl_verify_depth 1;

上下文

http, server

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

错误处理#

http_ssl 模块支持若干非标准错误代码,可用于使用 error_page 指令进行重定向:

495

客户端证书验证期间发生错误;

496

客户端未提供所需的证书;

497

常规请求已发送到 HTTPS 端口。

重定向在请求完全解析后发生,变量如 $request_uri, $uri, $args 等可用时进行。

指定要更改的代理服务器响应头中“Set-Cookie”字段的路径属性中的文本。重定向在请求完全解析后进行,并且变量如 $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_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 early 数据且握手未完成,返回“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,否则返回“.”。