ngx_http_ssl_module 模块

ngx_http_ssl_module 模块提供了 HTTPS 所需的必要支持。

此模块默认未构建，应使用 --with-http_ssl_module 配置参数启用。

此模块需要 OpenSSL 库。

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

• 将 worker 进程 的数量设置为处理器数量,
• 启用 keep-alive 连接,
• 启用 共享 会话缓存,
• 禁用 内置 会话缓存,
• 可能增加会话 生命周期（默认为 5 分钟）:

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/nginx/conf/cert.pem;
        ssl_certificate_key /usr/local/nginx/conf/cert.key;
        ssl_session_cache   shared:SSL:10m;
        ssl_session_timeout 10m;

        ...
    }

ssl off;

该指令在版本 1.15.0 中已废弃，并在版本 1.25.1 中移除。应使用listen指令的ssl参数。

ssl_buffer_size 16k;

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

默认情况下，缓冲区大小为16k，这对于发送大型响应时有最小的开销。为了将首字节时间最小化，可能有利于使用较小的值，例如：

ssl_buffer_size 4k;

为给定虚拟服务器指定一个以 PEM 格式的证书文件。如果还应该指定中间证书以及主要证书，则应该按照以下顺序在同一个文件中指定：主要证书首先，然后是中间证书。一个以 PEM 格式的密钥也可以放置在同一个文件中。

自版本 1.11.0 起，可以多次指定此指令以加载不同类型的证书，例如，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 或更高版本支持不同证书的单独证书链。在旧版本中，只能使用一个证书链。

自版本 1.15.9 起，当使用 OpenSSL 1.0.2 或更高版本时，可以在file名称中使用变量：

ssl_certificate     $ssl_server_name.crt;
ssl_certificate_key $ssl_server_name.key;

请注意，使用变量意味着每次 SSL 握手都会加载一个证书，这可能对性能产生负面影响。

可以指定值data:$variable代替file（1.15.10），这会从变量中加载证书，而不使用中间文件。请注意，不适当使用此语法可能会产生安全影响，例如将密钥数据写入错误日志。

应该记住，由于 HTTPS 协议对最大互操作性的限制，虚拟服务器应该监听不同的 IP 地址。

为给定虚拟服务器指定一个以 PEM 格式的密钥文件。

The value engine:name:id can be specified instead of the file (1.7.9), which loads a secret key with a specified id from the OpenSSL engine name.

The value data:$variable can be specified instead of the file (1.15.10), which loads a secret key from a variable without using intermediate files. Note that inappropriate use of this syntax may have its security implications, such as writing secret key data to error log.

Since version 1.15.9, variables can be used in the file name when using OpenSSL 1.0.2 or higher.

ssl_ciphers HIGH:!aNULL:!MD5;

Specifies the enabled ciphers. The ciphers are specified in the format understood by the OpenSSL library, for example:

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

The full list can be viewed using the “openssl ciphers” command.

The previous versions of nginx used different ciphers by default.

Specifies a file with trusted CA certificates in the PEM format used to verify client certificates and OCSP responses if ssl_stapling is enabled.

The list of certificates will be sent to clients. If this is not desired, the ssl_trusted_certificate directive can be used.

Sets arbitrary OpenSSL configuration commands.

The directive is supported when using OpenSSL 1.0.2 or higher.

Several ssl_conf_command directives can be specified on the same level:

ssl_conf_command Options PrioritizeChaCha;
ssl_conf_command Ciphersuites TLS_CHACHA20_POLY1305_SHA256;

These directives are inherited from the previous configuration level if and only if there are no ssl_conf_command directives defined on the current level.

Note that configuring OpenSSL directly might result in unexpected behavior.

Specifies a file with revoked certificates (CRL) in the PEM format used to verify client certificates.

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

默认情况下，没有设置参数，因此不会使用DHE密码。

在版本1.11.0之前，默认使用内置参数。

ssl_early_data off;

启用或禁用TLS 1.3 早期数据。

早期数据发送的请求容易受到重放攻击。为了在应用层防范此类攻击，应使用$ssl_early_data变量。

proxy_set_header Early-Data $ssl_early_data;

该指令在使用OpenSSL 1.1.1或更高版本（1.15.4）和BoringSSL时支持。

ssl_ecdh_curve auto;

指定ECDHE密码的curve。

当使用OpenSSL 1.0.2或更高版本时，可以指定多个曲线（1.11.0），例如：

ssl_ecdh_curve prime256v1:secp384r1;

特殊值auto（1.11.0）指示nginx在使用OpenSSL 1.0.2或更高版本时使用OpenSSL库中的列表，或在使用旧版本时使用prime256v1。

在版本1.11.0之前，默认使用prime256v1曲线。

当使用OpenSSL 1.0.2或更高版本时，此指令设置服务器支持的曲线列表。因此，为了使ECDSA证书正常工作，重要的是包括证书中使用的曲线。

ssl_ocsp off;

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

为了使OCSP验证工作，ssl_verify_client指令应设置为on或optional。

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

示例：

ssl_verify_client on;
ssl_ocsp          on;
resolver          192.0.2.1;

ssl_ocsp_cache off;

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

off 参数禁止使用缓存。

覆盖用于 OCSP 验证客户端证书的“授权信息访问”证书扩展中指定的 OCSP 响应者 URL。

仅支持“http://” OCSP 响应者：

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

指定一个包含密钥的 文件，其中每个密钥都在单独的行上指定。在加载密钥时依次尝试这些密钥。

示例：

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;

        # named pipe can also be used instead of a file
        ssl_password_file /etc/keys/fifo;
        ssl_certificate_key /etc/keys/second.key;
    }
}

ssl_prefer_server_ciphers off;

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

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

启用指定的协议。

如果在服务器级别指定了该指令，则可以使用默认服务器的值。在“虚拟服务器选择”部分提供了详细信息。

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

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

TLSv1.3 参数从 1.23.4 开始默认为开启状态。

ssl_reject_handshake off;

如果启用，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 none;

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

off

严格禁止使用会话缓存：nginx 明确告知客户端不得重用会话。

none

轻松禁止使用会话缓存：nginx 告知客户端可以重用会话，但实际上不在缓存中存储会话参数。

builtin

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

shared

所有工作进程共享的缓存。缓存大小以字节为单位指定；1 MB 可以存储约 4000 个会话。每个共享缓存都应具有任意名称。具有相同名称的缓存可在多个虚拟服务器中使用。它还用于自动生成、存储和定期轮换 TLS 会话票据密钥（1.23.2），除非使用 ssl_session_ticket_key 指令显式配置。

两种缓存类型可以同时使用，例如：

ssl_session_cache builtin:1000 shared:SSL:10m;

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

设置用于加密和解密 TLS 会话票据的 file。如果同一个密钥必须在多个服务器之间共享，则需要该指令。默认情况下，将使用随机生成的密钥。

如果指定了多个密钥，则仅使用第一个密钥来加密 TLS 会话票据。这允许配置密钥轮换，例如：

ssl_session_ticket_key current.key;
ssl_session_ticket_key previous.key;

该 file 必须包含 80 或 48 字节的随机数据，并可以使用以下命令创建：

openssl rand 80 > ticket.key

根据文件大小使用 AES256（对于 80 字节密钥，1.11.8）或 AES128（对于 48 字节密钥）进行加密。

ssl_session_tickets on;

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

ssl_session_timeout 5m;

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

ssl_stapling off;

通过服务器启用或禁用OCSP响应的装订。 示例：

ssl_stapling on;
resolver 192.0.2.1;

为使OCSP装订工作，应了解服务器证书颁发机构的证书。 如果ssl_certificate文件不包含中间证书，服务器证书颁发机构的证书应出现在ssl_trusted_certificate文件中。

要解析OCSP响应主机名，还应指定解析器指令。

设置后，将从指定的文件中获取装订的OCSP响应，而不是查询服务器证书中指定的OCSP响应器。

该文件应采用“openssl ocsp”命令生成的DER格式。

覆盖在证书扩展“Authority Information Access”中指定的OCSP响应器的URL。

仅支持“http://” OCSP响应器：

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

ssl_stapling_verify off;

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

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

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

与由ssl_client_certificate设置的证书相比，这些证书的列表不会发送给客户端。

ssl_verify_client off;

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

可选参数（0.8.7+）请求客户端证书并在证书存在时进行验证。

可选_no_ca参数（1.3.8，1.2.5）请求客户端证书，但不要求它由受信任的CA证书签名。这是用于在nginx外部执行实际证书验证的情况。证书的内容可以通过$ssl_client_cert变量访问。

ssl_verify_depth 1;

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

ngx_http_ssl_module模块支持几个非标准错误代码，可以使用error_page指令进行重定向：

495

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

496

客户端未提供所需证书；

497

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

在请求完全解析并且变量（例如$request_uri，$uri，$args等）可用之后进行重定向。

ngx_http_ssl_module模块支持嵌入式变量：

$ssl_alpn_protocol

返回SSL握手期间由ALPN选定的协议，否则返回空字符串（1.21.4）;

$ssl_cipher

返回已建立SSL连接所使用的密码的名称;

$ssl_ciphers

返回客户端支持的密码列表（1.11.7）。已知密码按名称列出，未知密码以十六进制显示，例如：

AES128-SHA:AES256-SHA:0x00ff

该变量仅在使用OpenSSL 1.0.2或更高版本时完全支持。使用旧版本时，该变量仅对新会话可用，并且仅列出已知密码。

$ssl_client_escaped_cert

返回已建立SSL连接的客户端证书的PEM格式（经过URL编码）（1.13.5）;

$ssl_client_cert

返回已建立SSL连接的客户端证书的PEM格式，除第一行外的每行都以制表符前缀； 这是为了在proxy_set_header指令中使用;

该变量已过时，应改用$ssl_client_escaped_cert变量。

$ssl_client_fingerprint

返回已建立SSL连接的客户端证书的SHA1指纹（1.7.1）;

$ssl_client_i_dn

返回已建立SSL连接的客户端证书的“issuer DN”字符串，根据RFC 2253（1.11.6）;

$ssl_client_i_dn_legacy

返回已建立SSL连接的客户端证书的“issuer DN”字符串;

在1.11.6版本之前，变量名为$ssl_client_i_dn。

$ssl_client_raw_cert

返回已建立SSL连接的客户端证书的PEM格式;

$ssl_client_s_dn

返回已建立SSL连接的客户端证书的“subject DN”字符串，根据RFC 2253（1.11.6）;

$ssl_client_s_dn_legacy

返回已建立SSL连接的客户端证书的“subject DN”字符串;

在1.11.6版本之前，变量名为$ssl_client_s_dn。

$ssl_client_serial

返回已建立SSL连接的客户端证书的序列号;

$ssl_client_v_end

返回客户端证书的结束日期（1.11.7）;

$ssl_client_v_remain

返回客户端证书过期前的天数（1.11.7）;

$ssl_client_v_start

返回客户端证书的开始日期（1.11.7）;

$ssl_client_verify

返回客户端证书验证的结果：“成功”，“失败：原因”，如果证书不存在则返回“无”；

在版本1.11.7之前，“失败”的结果中不包含 原因 字符串。

$ssl_curve

返回SSL握手密钥交换过程中使用的协商曲线（1.21.5）。已知曲线以名称列出，未知曲线以十六进制显示，例如：

prime256v1

该变量仅在使用OpenSSL版本3.0或更高版本时受支持。对于较旧的版本，变量值将为空字符串。

$ssl_curves

返回客户端支持的曲线列表（1.11.7）。已知曲线以名称列出，未知曲线以十六进制显示，例如：

0x001d:prime256v1:secp521r1:secp384r1

该变量仅在使用OpenSSL版本1.0.2或更高版本时受支持。对于较旧的版本，变量值将为空字符串。

该变量仅适用于新会话。

$ssl_early_data

如果使用TLS 1.3 提前数据并且握手尚未完成，则返回“1”，否则返回“”（1.15.3）。

$ssl_protocol

返回已建立SSL连接的协议；

$ssl_server_name

返回通过SNI请求的服务器名称（1.7.0）；

$ssl_session_id

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

$ssl_session_reused

如果重用了SSL会话，则返回“r”，否则返回“.”（1.5.11）。