ngx_http_ssl_module モジュール

ngx_http_ssl_moduleモジュールはHTTPSに必要なサポートを提供します。

このモジュールはデフォルトではビルドされず、--with-http_ssl_module configureパラメータを有効にする必要があります。

このモジュールはOpenSSL ライブラリを必要とします。

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

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

worker_processes auto;

http {

    ...

    server {
        listen              443 ssl;
        keepalive_timeout   70;

        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;

        ...
    }

ssl off;

このディレクティブはバージョン 1.15.0 で廃止されました。listenディレクティブのssl パラメータが代わりに使われなければなりません。

ssl_buffer_size 16k;

データの送信に使われるバッファのサイズを設定する。

デフォルトではバッファサイズは16Kで、大きな応答を送信するときの最小限のオーバーヘッドと釣り合います。最初のバイトの時間を最小にするためには、小さな値が有効かも知れません。例えば:

ssl_buffer_size 4k;

指定されたサーバのための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つの証明書チェーンだけを使うことができます。

バージョン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アドレスでlistenしなければならないことを心に留めておく必要があります:

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

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

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

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

以前のバージョンのnginxはデフォルトでdifferent 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)のファイルを指定します。

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

デフォルトではパラメータは設定されないため、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 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_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検証のクライアント証明書の状態を格納するキャッシュの名前とサイズを設定します。キャッシュは全てのワーカープロセス間で共有されます。同じ名前のキャッシュは複数のサーバの中で使うことができます。

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

クライアント証明書の検証のための"Authority Information Access"証明書の拡張で指定されるOCSPレスポンダのURLを上書きします。

"http://" OCSP 応答者のみサポートされています。

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

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

ssl_protocols TLSv1 TLSv1.1 TLSv1.2;

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

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

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

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はクライアントにセッションが再利用できないかもしれないと伝え、実際にはキャッシュにセッションパラメータを保持しません。

ビルトイン

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;

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

ssl_stapling off;

サーバによるstapling of OCSP responses を有効または無効にします。例:

ssl_stapling on;
resolver 192.0.2.1;

OCSP staplingを動作させるには、サーバ証明書の発行者の証明書が知られていなければなりません。もしssl_certificate ファイルが中間証明書を含んでいなければ、サーバ証明書の発行者の証明書がssl_trusted_certificateファイルの中に存在しなければなりません。

OCSP 応答のホスト名の決定には、resolverディレクティブも指定されていなければなりません。

セットされた場合には、サーバ証明書の中のOCSP応答者へのクリエの代わりに、指定されたfileからstapled 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 ディレクティブを使って信頼できるものとして設定される必要があります。

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

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

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

AES128-SHA:AES256-SHA:0x00ff

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

$ssl_client_escaped_cert

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

$ssl_client_cert

SSL接続を確立するために使われたPEM形式のクライアント証明書を返します。それぞれの行は最初にtab文字があることを期待されます; これは proxy_set_header ディレクティブの中で使われる事を意図しています;

変数は非推奨です。代わりに$ssl_client_escaped_cert 変数が使われるべきです。

$ssl_client_fingerprint

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

$ssl_client_i_dn

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

$ssl_client_i_dn_legacy

確立されたSSL接続のためのクライアント証明書の"issuer DN"文字列を返します;

バージョン 1.11.6 以前は、変数名は $ssl_client_i_dnでした。

$ssl_client_raw_cert

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

$ssl_client_s_dn

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

$ssl_client_s_dn_legacy

確立されたSSL接続のためのクライアント証明書の"subject 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", "FAILEDreason"、証明書が存在しない場合は"NONE";

バージョン 1.11.7 以前は、"FAILED"の結果は reason 文字列を含んでいませんでした。

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