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

特定のサーバーの PEM 形式の証明書を格納した file を指定します。中間証明書をプライマリ証明書に加えて指定する必要がある場合は、同じファイルに次の順序で指定する必要があります。最初にプライマリ証明書、次に中間証明書です。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 つの証明書チェーンしか使用できません。

バージョン 1.15.9 以降、OpenSSL 1.0.2 以降を使用する場合、file 名で変数を使用できます。

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

変数を使用すると、SSL ハンドシェイクごとに証明書がロードされ、パフォーマンスに悪影響を与える可能性があることに注意してください。

file の代わりに値 data:$variable を指定でき (1.15.10)、これにより、中間ファイルを使用せずに変数から証明書がロードされます。この構文の不適切な使用は、エラーログ に秘密鍵データが書き込まれるなど、セキュリティ上の影響がある可能性があることに注意してください。

特定のサーバーの PEM 形式の秘密鍵を格納した file を指定します。

file の代わりに、値 engine:name:id を指定でき、これにより、指定された id を持つ秘密鍵が OpenSSL エンジン name からロードされます。

file の代わりに値 data:$variable を指定でき (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" コマンドを使用して表示できます。

検証クライアント証明書と ssl_stapling が有効な場合は OCSP 応答に使用される、PEM 形式の信頼された CA 証明書を含む file を指定します。

証明書のリストはクライアントに送信されます。これが望ましくない場合は、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 を直接設定すると、予期しない動作になる可能性があることに注意してください。

クライアント証明書を 検証 するために使用される、PEM 形式の失効した証明書 (CRL) を格納した file を指定します。

DHE 暗号化の DH パラメーターを格納した file を指定します。

デフォルトではパラメータは設定されないため、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) は、OpenSSL 1.0.2 以降を使用する場合は OpenSSL ライブラリに組み込まれたリストを使用し、古いバージョンの場合は prime256v1 を使用するように nginx に指示します。

バージョン 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;

OCSP 検証のためにクライアント証明書のステータスを保存するキャッシュの name と size を設定します。キャッシュはすべてのワーカープロセス間で共有されます。同じ名前のキャッシュは、複数の仮想サーバーで使用できます。

off パラメーターは、キャッシュの使用を禁止します。

クライアント証明書の 検証 のために、"Authority Information Access" 証明書拡張で指定された 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;

指定されたプロトコルを有効にします。

ディレクティブが server レベルで指定されている場合、デフォルトサーバーの値を使用できます。

TLSv1.1 および TLSv1.2 パラメーターは、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 に組み込まれたキャッシュ。1 つのワーカープロセスでのみ使用されます。キャッシュサイズはセッション単位で指定します。サイズが指定されていない場合は、20480 セッションに等しくなります。組み込みキャッシュを使用すると、メモリの断片化が発生する可能性があります。

shared

すべてのワーカープロセス間で共有されるキャッシュ。キャッシュサイズはバイト単位で指定します。1 メガバイトには約 4000 セッションを格納できます。各共有キャッシュには、任意の名前が必要です。同じ名前のキャッシュは、複数のサーバーで使用できます。また、ssl_session_ticket_key ディレクティブを使用して明示的に構成されていない限り、TLS セッションチケットキーを自動的に生成、保存、および定期的にローテーションするためにも使用されます (1.23.2)。

両方のキャッシュタイプを同時に使用できます。例えば、

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レスポンダのホスト名の解決には、resolverディレクティブも指定する必要があります。

設定されている場合、ステープルされたOCSPレスポンスは、サーバー証明書に指定されたOCSPレスポンダへのクエリの代わりに、指定されたfileから取得されます。

ファイルは、"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ディレクティブを使用して信頼済みとして構成されている必要があります。

検証クライアント証明書と ssl_stapling が有効な場合は OCSP 応答に使用される、PEM 形式の信頼された CA 証明書を含む file を指定します。

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）。既知の暗号は名前でリストされ、不明な暗号は16進数で表示されます。例:

AES128-SHA:AES256-SHA:0x00ff

この変数は、OpenSSLバージョン1.0.2以降を使用している場合にのみ完全にサポートされます。古いバージョンでは、変数は新しいセッションでのみ使用可能で、既知の暗号のみをリストします。

$ssl_client_cert

確立されたSSL接続のクライアント証明書をPEM形式で返します。最初の行を除く各行はタブ文字で始まるように整形されます（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）。既知の曲線は名前でリストされ、不明な曲線は16進数で表示されます。例:

prime256v1

この変数は、OpenSSLバージョン3.0以降を使用している場合にのみサポートされます。古いバージョンでは、変数の値は空の文字列になります。

$ssl_curves

クライアントによってサポートされる曲線のリストを返します（1.11.7）。既知の曲線は名前でリストされ、不明な曲線は16進数で表示されます。例:

0x001d:prime256v1:secp521r1:secp384r1

この変数は、OpenSSLバージョン1.0.2以降を使用している場合にのみサポートされます。古いバージョンでは、変数の値は空の文字列になります。

この変数は新しいセッションでのみ使用可能です。

$ssl_protocol

確立されたSSL接続のプロトコルを返します。

$ssl_server_name

SNIを介してリクエストされたサーバー名を返します。

$ssl_session_id

確立されたSSL接続のセッション識別子を返します。

$ssl_session_reused

SSLセッションが再利用された場合は「r」を返し、それ以外の場合は「.」を返します。