ngx_http_ssl_module 模組

ngx_http_ssl_module 模組提供了 HTTPS 所需的支援。

此模組預設不會建置，應使用 --with-http_ssl_module 配置參數啟用。

此模組需要 OpenSSL 程式庫。

為減少處理器負載，建議：

• 將 工作程序 的數量設定為等於處理器的數量、
• 啟用 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;

指定一個 file，其中包含給定虛擬伺服器的 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 位址。

指定一個 file，其中包含給定虛擬伺服器的 PEM 格式密鑰。

可以使用 engine:name:id 值來取代 file (1.7.9)，該值會從 OpenSSL 引擎 name 載入具有指定 id 的密鑰。

可以使用 data:$variable 值來取代 file (1.15.10)，該值會從變數載入密鑰，而無需使用中繼檔案。請注意，不當使用此語法可能會產生安全性影響，例如將密鑰資料寫入錯誤日誌。

自 1.15.9 版本起，在使用 OpenSSL 1.0.2 或更高版本時，可以在 file 名稱中使用變數。

ssl_ciphers HIGH:!aNULL:!MD5;

指定啟用的密碼。密碼以 OpenSSL 程式庫理解的格式指定，例如：

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

可以使用 “openssl ciphers” 命令檢視完整清單。

nginx 的先前版本預設使用不同的密碼。

指定一個 file，其中包含 PEM 格式的受信任 CA 憑證，用於驗證用戶端憑證和 OCSP 回應（如果啟用 ssl_stapling）。

憑證清單將傳送給用戶端。如果不需要這樣做，可以使用 ssl_trusted_certificate 指令。

設定任意 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 可能會導致意外行為。

指定一個 file，其中包含 PEM 格式的已撤銷憑證 (CRL)，用於驗證用戶端憑證。

指定一個 file，其中包含 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 金鑰的記錄，並指定金鑰記錄檔的路徑。金鑰以與 Wireshark 相容的 SSLKEYLOGFILE 格式記錄。

此指令是我們商業訂閱的一部分。

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 驗證的用戶端憑證狀態的快取的 name 和 size。快取在所有工作程序之間共用。具有相同名稱的快取可以在多個虛擬伺服器中使用。

off 參數禁止使用快取。

覆寫 “Authority Information Access” 憑證擴展中指定的 OCSP 回應器 URL，用於驗證用戶端憑證。

僅支援 “http://” OCSP 回應器。

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

指定一個 file，其中包含 密鑰的密碼，其中每個密碼在單獨的一行中指定。載入金鑰時，會依次嘗試密碼。

範例

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;

啟用指定的協定。

如果在 server 層級指定指令，可以使用預設伺服器的值。詳細資訊請參閱 “虛擬伺服器選擇” 章節。

只有在使用 OpenSSL 1.0.1 或更高版本時，TLSv1.1 和 TLSv1.2 參數 (1.1.13, 1.0.12) 才有效。

只有在使用 OpenSSL 1.1.1 或更高版本時，TLSv1.3 參數 (1.13.0) 才有效。

自 1.23.4 起，預設使用 TLSv1.3 參數。

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

一個在所有 worker 程序之間共享的快取。快取大小以位元組指定；一百萬位元組可以儲存約 4000 個會話。每個共享快取都應該有一個任意名稱。具有相同名稱的快取可以在多個虛擬伺服器中使用。它也用於自動產生、儲存和定期輪換 TLS 會話票證金鑰 (1.23.2)，除非使用 ssl_session_ticket_key 指令明確配置。

兩種快取類型可以同時使用，例如

ssl_session_cache builtin:1000 shared:SSL:10m;

但是只使用共享快取而不使用內建快取應該更有效率。

設定一個 file，其中包含用於加密和解密 TLS 會話票證的密鑰。如果多個伺服器之間必須共享相同的金鑰，則此指令是必要的。預設情況下，會使用隨機產生的金鑰。

如果指定了多個金鑰，則只有第一個金鑰用於加密 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 回應程式的主機名稱，還應該指定 resolver 指令。

設定後，釘選的 OCSP 回應將從指定的 file 中取得，而不是查詢伺服器憑證中指定的 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 指令設定為信任憑證。

指定一個 file，其中包含 PEM 格式的受信任 CA 憑證，用於驗證用戶端憑證和 OCSP 回應（如果啟用 ssl_stapling）。

與 ssl_client_certificate 設定的憑證不同，這些憑證的列表不會傳送給客戶端。

ssl_verify_client off;

啟用客戶端憑證的驗證。驗證結果儲存在 $ssl_client_verify 變數中。

optional 參數 (0.8.7+) 會請求客戶端憑證，並且如果存在憑證，則會驗證該憑證。

optional_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 (urlencoded) (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

根據 RFC 2253 傳回已建立的 SSL 連線的客戶端憑證的「頒發者 DN」字串 (1.11.6)；

$ssl_client_i_dn_legacy

傳回已建立的 SSL 連線的客戶端憑證的「頒發者 DN」字串；

在 1.11.6 版本之前，變數名稱為 $ssl_client_i_dn。

$ssl_client_raw_cert

傳回已建立的 SSL 連線的客戶端憑證，格式為 PEM；

$ssl_client_s_dn

根據 RFC 2253 傳回已建立的 SSL 連線的客戶端憑證的「主體 DN」字串 (1.11.6)；

$ssl_client_s_dn_legacy

傳回已建立的 SSL 連線的客戶端憑證的「主體 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

傳回客戶端憑證驗證的結果：「SUCCESS」、「FAILED:reason」，如果不存在憑證，則傳回「NONE」；

在 1.11.7 版本之前，「FAILED」結果不包含 reason 字串。

$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)。