モジュール ngx_http_ssl_module

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

このモジュールはデフォルトではビルドされません。--with-http_ssl_module 設定パラメータを使用して有効にする必要があります。

このモジュールには、OpenSSL ライブラリが必要です。

プロセッサの負荷を軽減するために、

• ワーカープロセス数をプロセッサ数に等しく設定し、
• キープアライブ接続を有効にし、
• 共有セッションキャッシュを有効にし、
• 組み込みセッションキャッシュを無効にし、
• 場合によっては、セッションの有効期間（デフォルトは5分）を長くする

worker_processes auto;

http {

    ...

    server {
        listen              443 ssl;
        keepalive_timeout   70;

        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パラメータを代わりに使用してください。

ssl_buffer_size 16k;

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

デフォルトでは、バッファサイズは16kで、大きなレスポンスを送信する場合のオーバーヘッドは最小限です。Time To First Byteを最小限にするには、より小さな値（例：

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以降を使用する場合は、ファイル名に変数を用いることができます。

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

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

中間ファイルを使用せずに変数から証明書をロードするファイルの代わりにdata:$変数を指定できます（1.15.10）。この構文を不適切に使用すると、秘密鍵データをエラーログに書き込むなどのセキュリティ上の問題が発生する可能性があります。

HTTPSプロトコルの相互運用性の制約により、仮想サーバーは異なるIPアドレスでリスンする必要があることに注意してください。

指定された仮想サーバーのPEM形式の秘密鍵を含むファイルを指定します。

ファイルの代わりにengine:名前:IDを指定できます（1.7.9）。これは、指定されたIDを持つ秘密鍵をOpenSSLエンジン名前からロードします。

中間ファイルを使用せずに変数から秘密鍵をロードするファイルの代わりにdata:$変数を指定できます（1.15.10）。この構文を不適切に使用すると、秘密鍵データをエラーログに書き込むなどのセキュリティ上の問題が発生する可能性があります。

バージョン1.15.9以降、OpenSSL 1.0.2以降を使用する場合は、ファイル名に変数を用いることができます。

ssl_ciphers HIGH:!aNULL:!MD5;

有効な暗号スイートを指定します。暗号スイートは、OpenSSLライブラリで理解できる形式で指定します。例：

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

完全なリストは、「openssl ciphers」コマンドを使用して表示できます。

以前のバージョンのnginxは、デフォルトで異なる暗号スイートを使用していました。

クライアント証明書と、ssl_staplingが有効になっている場合のOCSPレスポンスを検証するために使用される、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暗号スイート用のDHパラメータを含むファイルを指定します。

デフォルトではパラメータは設定されず、そのため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暗号スイートの曲線を指定します。

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キーのログを有効にし、キーログファイルへのパスを指定します。キーは、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検証のクライアント証明書のステータスを格納するキャッシュの名前とサイズを設定します。キャッシュはすべてのワーカープロセス間で共有されます。同じ名前のキャッシュを複数の仮想サーバーで使用できます。

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

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

「http://」OCSPレスポンダのみがサポートされます。

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

秘密鍵のパスフレーズを含むファイルを指定します。各パスフレーズは別々の行に指定されます。キーを読み込む際には、パスフレーズが順番に試されます。

例

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プロトコルを使用する場合、サーバーの暗号スイートをクライアントの暗号スイートよりも優先するように指定します。

ssl_protocols TLSv1 TLSv1.1 TLSv1.2 TLSv1.3;

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

serverレベルでディレクティブが指定されている場合、デフォルトサーバーの値を使用できます。詳細は、「仮想サーバーの選択」セクションを参照してください。

TLSv1.1とTLSv1.2パラメータ（1.1.13、1.0.12）は、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証明書を含むファイルを指定します。

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

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

AES128-SHA:AES256-SHA:0x00ff

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

$ssl_client_escaped_cert

確立されたSSL接続のクライアント証明書をPEM形式（URLエンコード）で返します（1.13.5）。

$ssl_client_cert

確立されたSSL接続のクライアント証明書をPEM形式で返します。最初の行を除く各行の先頭にタブ文字が付加されます。これはproxy_set_headerディレクティブでの使用を目的としています。

この変数は非推奨です。$ssl_client_escaped_cert変数を使用する必要があります。

$ssl_client_fingerprint

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

$ssl_client_i_dn

確立されたSSL接続のクライアント証明書の「発行者DN」文字列をRFC 2253に従って返します（1.11.6）。

$ssl_client_i_dn_legacy

確立されたSSL接続のクライアント証明書の「発行者DN」文字列を返します。

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

$ssl_client_raw_cert

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

$ssl_client_s_dn

確立されたSSL接続のクライアント証明書の「サブジェクトDN」文字列をRFC 2253に従って返します（1.11.6）。

$ssl_client_s_dn_legacy

確立されたSSL接続のクライアント証明書の「サブジェクト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」、「FAILED:reason」、および証明書が存在しない場合は「NONE」。

バージョン1.11.7より前は、「FAILED」の結果にはreason文字列が含まれていませんでした。

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