ngx_mail_ssl_module 模組

ngx_mail_ssl_module 模組提供了郵件代理伺服器使用 SSL/TLS 協定所需的必要支援。

這個模組預設不會建置，應該使用 --with-mail_ssl_module 組態參數啟用。

這個模組需要 OpenSSL 程式庫。

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

• 設定工作處理程序數量等於處理器數量，
• 啟用共享的會話快取，
• 停用內建的會話快取，
• 並可能增加會話存活時間（預設為 5 分鐘）

worker_processes auto;

mail {

    ...

    server {
        listen              993 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;

        ...
    }

ssl off;

這個指令在 1.15.0 版本中已過時，並在 1.25.1 版本中移除。應改用 listen 指令的 ssl 參數。

指定一個 file，其中包含給定伺服器的 PEM 格式憑證。如果除了主要憑證外還應指定中繼憑證，則應在同一個檔案中依下列順序指定：先是主要憑證，然後是中繼憑證。PEM 格式的私密金鑰可以放在同一個檔案中。

從 1.11.0 版本開始，可以多次指定此指令，以載入不同類型的憑證，例如 RSA 和 ECDSA。

server {
    listen              993 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 或更高版本支援不同憑證的個別憑證鏈。在較舊的版本中，只能使用一個憑證鏈。

可以指定值 data:certificate 而不是 file (1.15.10)，這會載入憑證而無需使用中繼檔案。請注意，不當使用此語法可能會產生安全性隱憂，例如將私密金鑰資料寫入錯誤日誌。

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

可以指定值 engine:name:id 而不是 file (1.7.9)，這會從 OpenSSL 引擎 name 載入具有指定 id 的私密金鑰。

可以指定值 data:key 而不是 file (1.15.10)，這會載入私密金鑰而無需使用中繼檔案。請注意，不當使用此語法可能會產生安全性隱憂，例如將私密金鑰資料寫入錯誤日誌。

ssl_ciphers HIGH:!aNULL:!MD5;

指定已啟用的加密演算法。加密演算法是以 OpenSSL 程式庫可以理解的格式指定，例如

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

可以使用「openssl ciphers」命令檢視完整清單。

先前版本的 nginx 預設使用不同的加密演算法。

指定一個 file，其中包含 PEM 格式的受信任 CA 憑證，用於驗證用戶端憑證。

憑證清單將會傳送給用戶端。如果不希望這樣，可以使用 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;

當使用 OpenSSL 1.0.2 或更高版本時，特殊值 auto (1.11.0) 會指示 nginx 使用內建於 OpenSSL 程式庫的清單，或是在較舊的版本中使用 prime256v1。

在 1.11.0 版本之前，預設使用 prime256v1 曲線。

當使用 OpenSSL 1.0.2 或更高版本時，此指令會設定伺服器支援的曲線清單。因此，為了讓 ECDSA 憑證能夠運作，務必包含憑證中使用的曲線。

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

範例

mail {
    ssl_password_file /etc/keys/global.pass;
    ...

    server {
        server_name mail1.example.com;
        ssl_certificate_key /etc/keys/first.key;
    }

    server {
        server_name mail2.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;

啟用指定的協定。

只有在使用 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_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;

但僅使用共用快取而不使用內建快取應該會更有效率。

設定一個 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;

指定用戶端可以重複使用會話參數的時間長度。

指定一個 file，其中包含 PEM 格式的受信任 CA 憑證，用於驗證用戶端憑證。

與 ssl_client_certificate 設定的憑證不同，這些憑證的清單不會傳送給用戶端。

ssl_verify_client off;

啟用用戶端憑證驗證。驗證結果會在驗證請求的「Auth-SSL-Verify」標頭中傳遞。

optional 參數會請求用戶端憑證，如果存在憑證則驗證該憑證。

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

ssl_verify_depth 1;

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

starttls off;

on

允許使用 POP3 的 STLS 命令以及 IMAP 和 SMTP 的 STARTTLS 命令；

off

關閉

拒絕使用 STLS 和 STARTTLS 命令；

only