ngx_stream_ssl_module 模組

ngx_stream_ssl_module 模組 (1.9.0) 為串流代理伺服器提供使用 SSL/TLS 協定所需的支援。此模組預設不會建置，應使用 --with-stream_ssl_module 設定參數啟用。

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

• 將工作程序的數量設定為等於處理器的數量；
• 啟用共用的會話快取；
• 停用內建的會話快取；
• 並可能增加會話生命週期 (預設為 5 分鐘)

worker_processes auto;

stream {

    ...

    server {
        listen              12345 ssl;

        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;

        ...
    }

指定支援的 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;
}

指定一個 file，其中包含給定伺服器的 PEM 格式憑證。如果除了主憑證之外還應指定中間憑證，則它們應按以下順序在同一個檔案中指定：首先是主憑證，然後是中間憑證。PEM 格式的密鑰可以放在同一個檔案中。

自 1.11.0 版本起，此指令可以多次指定，以載入不同類型的憑證，例如 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 或更高版本支援不同憑證的個別憑證鏈。使用較舊版本時，只能使用一個憑證鏈。

自 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)，這會從變數載入憑證，而無需使用中間檔案。請注意，不當使用此語法可能會對安全性產生影響，例如將密鑰資料寫入錯誤日誌。

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

可以使用 engine:name:id 值來取代 file，這會從 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」命令檢視完整清單。

指定一個 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_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_handshake_timeout 60s;

指定 SSL 交握完成的逾時時間。

啟用用戶端連線 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;

設定快取的 name 和 size，該快取會儲存用戶端憑證狀態以進行 OCSP 驗證。快取在所有工作程序之間共用。具有相同名稱的快取可以在多個虛擬伺服器中使用。

off 參數會禁止使用快取。

覆寫在「授權資訊存取」憑證擴充中指定的 OCSP 回應者 URL，以進行用戶端憑證的驗證。

僅支援「http://」OCSP 回應者

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

指定一個 file，其中包含密鑰的通行詞組，每個通行詞組在不同的行上指定。載入金鑰時，會依序嘗試通行詞組。

範例

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;

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

啟用指定的協定。

如果在伺服器層級上指定指令，則可以使用預設伺服器的值。

只有在使用 OpenSSL 1.0.1 或更高版本時，TLSv1.1 和 TLSv1.2 參數才能運作。

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

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

ssl_reject_handshake off;

如果啟用，將會拒絕伺服器區塊中的 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

在所有工作程序之間共用的快取。快取大小以位元組為單位指定；一個兆位元組可以儲存約 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 回應程式。

該檔案應為 DER 格式，如 "openssl ocsp" 命令所產生的。

覆寫憑證的「授權資訊存取」擴展中指定的 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 參數會請求用戶端憑證，如果存在憑證則會驗證它。

optional_no_ca 參數會請求用戶端憑證，但不要求憑證必須由受信任的 CA 憑證簽署。這適用於 nginx 外部的服務執行實際憑證驗證的情況。憑證的內容可透過 $ssl_client_cert 變數存取。

ssl_verify_depth 1;

設定用戶端憑證鏈中的驗證深度。

ngx_stream_ssl_module 模組自 1.11.2 版本起支援變數。

$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_cert

傳回已建立的 SSL 連線的用戶端憑證，格式為 PEM，除了第一行之外，每一行都加上 tab 字元 (1.11.8)；

$ssl_client_fingerprint

傳回已建立的 SSL 連線的用戶端憑證 SHA1 指紋 (1.11.8)；

$ssl_client_i_dn

根據 RFC 2253，傳回已建立的 SSL 連線的用戶端憑證的「簽發者 DN」字串 (1.11.8)；

$ssl_client_raw_cert

傳回已建立的 SSL 連線的用戶端憑證，格式為 PEM (1.11.8)；

$ssl_client_s_dn

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

$ssl_client_serial

傳回已建立的 SSL 連線的用戶端憑證的序號 (1.11.8)；

$ssl_client_v_end

傳回用戶端憑證的結束日期 (1.11.8)；

$ssl_client_v_remain

傳回用戶端憑證到期前的剩餘天數 (1.11.8)；

$ssl_client_v_start

傳回用戶端憑證的開始日期 (1.11.8)；

$ssl_client_verify

傳回用戶端憑證驗證的結果 (1.11.8)：如果存在憑證則傳回 "SUCCESS"、"FAILED:reason"，如果不存在憑證則傳回 "NONE"；

$ssl_curve

傳回 SSL 交握金鑰交換過程所協商的曲線 (1.21.5)。已知的曲線以名稱列出，未知的曲線以十六進位顯示，例如

prime256v1

此變數僅在使用 OpenSSL 3.0 或更高版本時才支援。在舊版本中，此變數值將為空字串。

$ssl_curves

傳回用戶端支援的曲線列表 (1.11.7)。已知的曲線以名稱列出，未知的曲線以十六進位顯示，例如

0x001d:prime256v1:secp521r1:secp384r1

此變數僅在使用 OpenSSL 1.0.2 或更高版本時才支援。在舊版本中，此變數值將為空字串。

此變數僅適用於新會話。

$ssl_protocol

傳回已建立的 SSL 連線的協定；

$ssl_server_name

傳回透過 SNI 請求的伺服器名稱；

$ssl_session_id

傳回已建立的 SSL 連線的會話識別碼；

$ssl_session_reused

如果重複使用 SSL 會話則傳回 “r”，否則傳回 “.”。