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#

语法

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 版本。可以使用 openssl ciphers 命令查看完整列表。

ssl_client_certificate#

语法

ssl_client_certificate file;

默认

上下文

http, server

指定用于 验证 客户端证书和 OCSP 响应的 PEM 格式受信任 CA 证书文件,如果启用了 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

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

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

启用服务器端对 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#

语法

ssl_ocsp on | off | leaf;

默认

ssl_ocsp off;

上下文

http, server

启用客户端证书链的 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#

语法

ssl_ocsp_cache off | [shared:name:size];

默认

ssl_ocsp_cache off;

上下文

http, server

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

off 参数禁止使用缓存。

ssl_ocsp_responder#

语法

ssl_ocsp_responder uri;

默认

上下文

http, server

重写在 "Authority Information Access" 证书扩展中指定的 OCSP 响应者的 URI,以进行 验证 客户端证书。

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

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

ssl_password_file#

语法

ssl_password_file file;

默认

上下文

http, server

指定一个包含 秘密密钥 的文件,每个密码短语在单独的一行中指定。加载密钥时将依次尝试密码短语。

示例:

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.2 TLSv1.3;

上下文

http, server

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

启用指定的协议。

重要

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

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

ssl_reject_handshake#

语法

ssl_reject_handshake on | off;

默认

ssl_reject_handshake off;

上下文

http, server

如果启用,: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#

语法

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 响应的 stapling。示例:

ssl_stapling on;
resolver 127.0.0.53;

为了使 OCSP stapling 生效,服务器证书颁发者的证书应为已知。如果 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

指定用于 验证 客户端证书和 OCSP 响应的 PEM 格式的受信任 CA 证书文件,如果启用了 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#

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

$ssl_server_name#

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

$ssl_session_id#

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

$ssl_session_reused#

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