ngx_stream_ssl_module モジュール

ngx_stream_ssl_module モジュール(1.9.0)は、streamプロキシサーバがSSL/TLSプロトコルで動作するために必要なサポートを提供します。このモジュールはデフォルトでビルドされず、--with-stream_ssl_module configuration パラメータを有効にする必要があります。

プロセスの負荷を軽減するために、以下のことが推奨されます

• workerプロセス の数をプロセッサーの数と同じにする、
• 共有セッションキャッシュを有効にする、
• 作りつけのセッションキャッシュを無効にする、
• セッションの生存期間をできる限り増加する(デフォルトは5分):

worker_processes auto;

stream {

    ...

    server {
        listen              12345 ssl;

        ssl_protocols       TLSv1 TLSv1.1 TLSv1.2;
        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形式の証明書のファイルを指定します。中間証明書はプライマリ証明書に追加して指定されなければなりません。中間証明書は次の順番で同じファイルで指定されなければなりません: プリイマリ証明書が最初に来て、次に中間証明書がきます。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ハンドシェイクごとに証明書がロードされることを意味し、これはパフォーマンスに悪影響を及ぼす可能性があることに注意してください。

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

指定されたサーバのための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;

有効にするcipherを指定します。cipherはOpenSSLライブラリで理解される形式で指定されます。例えば:

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

全てのリストは"openssl ciphers"コマンドを使ってみることができます。

クライアントの証明書を検証するために使われる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を直接設定すると、予期しない動作が発生する可能性があることに注意してください。

クライアントの証明書を検証するために使われるPEM形式の失効した証明書(CRL)のファイルを指定します。

DHE cipherのためのDHパラメータのfileを指定します。

デフォルトではパラメータは設定されないため、DHE暗号は使われません。

バージョン 1.11.0より前は、組み込みパラメータがデフォルトで使われていました。

ssl_ecdh_curve auto;

ECDHE cipherのための curve を指定します。

OpenSSL 1.0.2 以上を使う場合は、multiple curvesを指定することができます (1.11.0)、たとえば:

ssl_ecdh_curve prime256v1:secp384r1;

OpenSSL 1.0.2以上あるいは古いバージョンでのprime256v1を使う場合、特別な値auto (1.11.0) はnginxにOpenSSLライブラリに組み込みのリストを使うように指示します。

バージョン 1.11.0より前では、prime256v1カーブがデフォルトで使われます。

OpenSSL 1.0.2以上を使う場合は、このディレクティブはサーバでサポートされるカーブのリストを設定します。従って ECDSA 証明書を動作させるには、証明書で使われるカーブを含めることが重要です。

ssl_handshake_timeout 60s;

SSLハンドシェイクの終了のタイムアウトを指定します。

secret keysのためのそれぞれのパスフレーズが一行に指定されている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プロトコルが使われる時に、サーバのcipherをクライアントのcipherよりも選ぶように指定します。

ssl_protocols TLSv1 TLSv1.1 TLSv1.2;

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

OpenSSL 1.0.1以上が使われたときにのみ、 TLSv1.1 と TLSv1.2 パラメータは動作するでしょう。

OpenSSL 1.1.1以上が使われた場合のみ、TLSv1.3 パラメータ (1.13.0) は動作します。

ssl_session_cache none;

セッションパラメータを保持するキャッシュのタイプとサイズを設定します。キャッシュは次のタイプのいずれかです:

off

セッションキャッシュの利用は厳密に禁止されています: nginxは明示的にクライアントにセッションが再利用できないかも知れないと伝えます。

none

セッションキャッシュの利用は穏やかに禁止されます: nginxはクライアントにセッションが再利用できないかもしれないと伝え、実際にはキャッシュにセッションパラメータを保持しません。

ビルトイン

OpenSSLのビルトインのキャッシュ; 一つのworkerプロセスのみで使われます。キャッシュサイズはセッションの中で定義されます。サイズが指定されない場合は、20480セッションになります。ビルトインのキャッシュを使うとメモリの断片化が起こるかも知れません。

shared

キャッシュは全てのworkerプロセスの間で共有されます。キャッシュサイズはbyteで指定され、1メガバイトは約4000セッションを保持することができます。それぞれの共有キャッシュは任意の名前を持つことができます。同じ名前のキャッシュは複数のサーバの中で使うことができます。

両方のキャッシュタイプを平行して使うことができます。例えば:

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-byte keys, 1.11.8) あるいは AES128 (48-byte keys) が暗号化のために使われます。

ssl_session_tickets on;

TLS session ticketsのセッション回復を有効または無効にします。

ssl_session_timeout 5m;

クライアントがセッションパラメータを再利用できる期間を指定します。

クライアントの証明書を検証するために使われるPEM形式のCA証明書のファイルを指定します。

ssl_client_certificateで設定される証明書に対して、これらの証明書のリストはクライアントに送られないでしょう。

ssl_verify_client off;

クライアントの証明書の検証を有効にする。検証の結果は$ssl_client_verify 変数の中に格納されます。クライアント証明書の検証中にエラーが発生したか、またはクライアントが必要とされる証明書を提示しなかった場合、接続は閉じられます。

optional パラメータ は、クライアントの証明書をリクエストし、存在していれば検証を行います。

optional_no_ca パラメータはクライアントの証明書をリクエストしますが、それが信頼できるCA証明書で署名されていることを要求しません。これは外部にサービスがある時にnginxに実際の証明書の検証を行うようにすることを意図しています。証明書の内容は$ssl_client_cert 変数を使ってアクセスすることができます。

ssl_verify_depth 1;

クライアント証明書チェーンの検証の深さを設定します。

1.11.2から、ngx_stream_ssl_module モジュールは変数をサポートします。

$ssl_alpn_protocol

SSLハンドシェイク時のALPNに選択されたプロトコルを返します。そうでなければ空の文字列が返されます (1.21.4);

$ssl_cipher

SSL接続を確立するために使われた暗号の名前を返します;

$ssl_ciphers

クライアントによってサポートされるcipherのリストを返します (1.11.7)。良く知られたcipherは名前でリスト化され、良く知られていないものは16進数で示されます。例えば:

AES128-SHA:AES256-SHA:0x00ff

OpenSSLバージョン 1.0.2以上を使う場合のみ、変数が完全にサポートされます。古いバージョンを使う場合、変数は新しいセッションについてのみ利用可能で、良く知られたcipherのみリスト化されます。

$ssl_client_cert

SSL接続を確立するために使われるPEM形式のクライアント証明書を返します。それぞれの行は最初にtab文字があることを期待されます (1.11.8);

$ssl_client_fingerprint

確立されるSSL接続のためのクライアント証明書のSHA1フィンガープリントを返します(1.11.8);

$ssl_client_i_dn

確立されたSSL接続のためのクライアント証明書の"issuer DN"文字列をRFC 2253に従って返します (1.11.8);

$ssl_client_raw_cert

確立されたSSL接続のためのPEM形式のクライアント証明書を返します (1.11.8);

$ssl_client_s_dn

確立されたSSL接続のためのクライアント証明書の"subject DN"文字列をRFC 2253に従って返します (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", "FAILEDreason"、証明書が存在しない場合は"NONE";

$ssl_curve

SSLハンドシェイクのキー交換プロセスで使われるネゴシエートされたカーブを返します(1.21.5)。良く知られたcurveは名前でリスト化され、良く知られていないものは16進数で示されます。例えば:

prime256v1

OpenSSLバージョン 3.0以上を使う場合のみ、変数がサポートされます。古いバージョンを使う場合は、変数の値は空文字になるでしょう。

$ssl_curves

クライアントによってサポートされるcurveのリストを返します (1.11.7)。良く知られたcurveは名前でリスト化され、良く知られていないものは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"を、そうでなければ"."を返します。