ngx_http_ssl_module モジュール
ngx_http_ssl_module
モジュールはHTTPSに必要なサポートを提供します。
このモジュールはデフォルトではビルドされず、--with-http_ssl_module
configureパラメータを有効にする必要があります。
このモジュールはOpenSSL ライブラリを必要とします。
設定例
プロセッサの負荷を削減するために、以下のことが推奨されます
- workerプロセスの数をプロセッサーの数と同じにする、
- keep-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 |
---|---|
デフォルト: |
ssl off; |
コンテキスト: |
http , server |
指定されたバーチャルサーバのHTTPSプロトコルを有効にする。
このディレクティブの代わりにlistenディレクティブのssl
パラメータを使うことがお勧めです。
構文: |
ssl_buffer_size |
---|---|
デフォルト: |
ssl_buffer_size 16k; |
コンテキスト: |
http , server |
このディレクティブはバージョン1.5.9から導入されました。
データの送信に使われるバッファのサイズを設定する。
デフォルトではバッファサイズは16Kで、大きな応答を送信するときの最小限のオーバーヘッドと釣り合います。最初のバイトの時間を最小にするためには、小さな値が有効かも知れません。例えば:
ssl_buffer_size 4k;
構文: |
ssl_certificate |
---|---|
デフォルト: | - |
コンテキスト: |
http , server |
指定されたサーバのための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つの証明書チェーンだけを使うことができます。
HTTPSプロトコルの制限により複数のバーチャルサーバは異なるIPアドレスでlistenしなければならないことを心に留めておく必要があります:
server { listen 192.168.1.1:443; server_name one.example.com; ssl_certificate one.example.com.crt; ... } server { listen 192.168.1.2:443; server_name two.example.com; ssl_certificate two.example.com.crt; ... }
そうでなければ、最初のサーバの証明書が二つ目のサイトのために発行されるでしょう。
構文: |
ssl_certificate_key |
---|---|
デフォルト: | - |
コンテキスト: |
http , server |
指定されたバーチャルサーバのためのPEM形式の秘密鍵のファイル
を指定します。
engine
:name
:id
の値は file
の代わりに指定することができ(1.7.9)、 特定のOpenSSLのname
の特定の id
と一緒に秘密鍵を取り付けます。
構文: |
ssl_ciphers |
---|---|
デフォルト: |
ssl_ciphers HIGH:!aNULL:!MD5; |
コンテキスト: |
http , server |
有効にするcipherを指定します。cipherはOpenSSLライブラリで理解される形式で指定されます。例えば:
ssl_ciphers ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;
全てのリストは"openssl ciphers
"コマンドを使ってみることができます。
以前のバージョンのnginxはデフォルトでdifferent ciphers を使っていました。
構文: |
ssl_client_certificate |
---|---|
デフォルト: | - |
コンテキスト: |
http , server |
クライアント証明書と、ssl_staplingが有効な時にはOCSP応答を検証するために使われるPEM形式の信頼されたCA証明書のfile
を指定します。
証明書のリストはクライアントに送信されるでしょう。これが望ましく無い場合、ssl_trusted_certificate ディレクティブを使うことができます。
構文: |
ssl_crl |
---|---|
デフォルト: | - |
コンテキスト: |
http , server |
このディレクティブはバージョン0.8.7から導入されました。
クライアントの証明書を検証するために使われるPEM形式の失効した証明書(CRL)のファイル
を指定します。
構文: |
ssl_dhparam |
---|---|
デフォルト: | - |
コンテキスト: |
http , server |
このディレクティブはバージョン0.7.2から導入されました。
DHE cipherのためのDHパラメータのfile
を指定します。
構文: |
ssl_ecdh_curve |
---|---|
デフォルト: |
ssl_ecdh_curve auto; |
コンテキスト: |
http , server |
このディレクティブはバージョン1.1.0と1.0.6から導入されました。
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
カーブがデフォルトで使われます。
構文: |
ssl_password_file |
---|---|
デフォルト: | - |
コンテキスト: |
http , server |
このディレクティブはバージョン1.7.3から導入されました。
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 |
---|---|
デフォルト: |
ssl_prefer_server_ciphers off; |
コンテキスト: |
http , server |
SSLv3とTLSプロトコルを使う時に、サーバのcipherをクライアントのcipherよりも選ぶように指定します。
構文: |
ssl_protocols
[ |
---|---|
デフォルト: |
ssl_protocols TLSv1 TLSv1.1 TLSv1.2; |
コンテキスト: |
http , server |
指定されたプロトコルを有効にします。バージョン1.0.1以上のOpenSSLライブラリが使われたときにのみ、 TLSv1.1
と TLSv1.2
パラメータは動作するでしょう。
バージョン 1.1.13と1.0.12からTLSv1.1
andTLSv1.2
パラメータがサポートされています。そのため古いnginxバージョンではOpenSSLのバージョン 1.0.1以上が使われます。これらのプロトコルは動作しますが、無効にすることができません。
構文: |
ssl_session_cache
|
---|---|
デフォルト: |
ssl_session_cache none; |
コンテキスト: |
http , server |
セッションパラメータを保持するキャッシュのタイプとサイズを設定します。キャッシュは次のタイプのいずれかです:
off
- セッションキャッシュの利用は厳密に禁止されています: nginxは明示的にクライアントにセッションが再利用できないかも知れないと伝えます。
none
- セッションキャッシュの利用は穏やかに禁止されます: nginxはクライアントにセッションが再利用できないかもしれないと伝え、実際にはキャッシュにセッションパラメータを保持しません。
ビルトイン
- OpenSSLのビルトインのキャッシュ; 一つのworkerプロセスのみで使われます。キャッシュサイズはセッションの中で定義されます。サイズが指定されない場合は、20480セッションになります。ビルトインのキャッシュを使うとメモリの断片化が起こるかも知れません。
shared
- キャッシュは全てのworkerプロセスの間で共有されます。キャッシュサイズはbyteで指定され、1メガバイトは約4000セッションを保持することができます。それぞれの共有キャッシュは任意の名前を持つことができます。同じ名前のキャッシュは複数のサーバの中で使うことができます。
両方のキャッシュタイプを平行して使うことができます。例えば:
ssl_session_cache builtin:1000 shared:SSL:10m;
ビルトインのキャッシュ無しで共有のキャッシュだけを使うほうがもっと効果的に違いありません。
構文: |
ssl_session_ticket_key |
---|---|
デフォルト: | - |
コンテキスト: |
http , server |
このディレクティブはバージョン1.5.7から導入されました。
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 |
---|---|
デフォルト: |
ssl_session_tickets on; |
コンテキスト: |
http , server |
このディレクティブはバージョン1.5.9から導入されました。
TLS session ticketsのセッション回復を有効または無効にします。
構文: |
ssl_session_timeout |
---|---|
デフォルト: |
ssl_session_timeout 5m; |
コンテキスト: |
http , server |
クライアントがセッションパラメータを再利用できる期間を指定します。
構文: |
ssl_stapling |
---|---|
デフォルト: |
ssl_stapling off; |
コンテキスト: |
http , server |
このディレクティブはバージョン1.3.7から導入されました。
サーバによるstapling of OCSP responses を有効または無効にします。例:
ssl_stapling on; resolver 192.0.2.1;
OCSP staplingを動作させるには、サーバ証明書の発行者の証明書が知られていなければなりません。もしssl_certificate ファイルが中間証明書を含んでいなければ、サーバ証明書の発行者の証明書がssl_trusted_certificateファイルの中に存在しなければなりません。
OCSP 応答のホスト名の決定には、resolverディレクティブも指定されていなければなりません。
構文: |
ssl_stapling_file |
---|---|
デフォルト: | - |
コンテキスト: |
http , server |
このディレクティブはバージョン1.3.7から導入されました。
セットされた場合には、サーバ証明書の中のOCSP応答者へのクリエの代わりに、指定されたfile
からstapled OCSP 応答が取り出されます。
ファイルは"openssl ocsp
"コマンドで生成されるDER形式でなければなりません。
構文: |
ssl_stapling_responder |
---|---|
デフォルト: | - |
コンテキスト: |
http , server |
このディレクティブはバージョン1.3.7から導入されました。
"Authority Information Access"証明書の拡張で指定されるOCSP応答者のURLを上書きします。
"http://
" OCSP 応答者のみサポートされています。
ssl_stapling_responder http://ocsp.example.com/;
構文: |
ssl_stapling_verify |
---|---|
デフォルト: |
ssl_stapling_verify off; |
コンテキスト: |
http , server |
このディレクティブはバージョン1.3.7から導入されました。
サーバによるOCSP応答の検証を有効または無効にします。
検証を動作させるには、サーバ証明書の発行者の証明書、ルート証明書、そして全ての中間証明書がssl_trusted_certificate ディレクティブを使って信頼できるものとして設定される必要があります。
構文: |
ssl_trusted_certificate |
---|---|
デフォルト: | - |
コンテキスト: |
http , server |
このディレクティブはバージョン1.3.7から導入されました。
クライアント証明書と、ssl_staplingが有効な時にはOCSP応答を検証するために使われるPEM形式の信頼されたCA証明書のfile
を指定します。
ssl_client_certificateで設定される証明書に対して、これらの証明書のリストはクライアントに送られないでしょう。
構文: |
ssl_verify_client
|
---|---|
デフォルト: |
ssl_verify_client off; |
コンテキスト: |
http , server |
クライアントの証明書の検証を有効にする。検証の結果は$ssl_client_verify 変数の中に格納されます。
optional
パラメータ (0.8.7+) は、クライアントの証明書をリクエストし、存在していれば検証を行います。
optional_no_ca
パラメータ(1.3.8, 1.2.5)はクライアントの証明書をリクエストしますが、それが信頼できるCA証明書で署名されていることを要求しません。これは外部にサービスがある時にnginxに実際の証明書の検証を行うようにすることを意図しています。証明書の内容は$ssl_client_cert 変数を使ってアクセスすることができます。
構文: |
ssl_verify_depth |
---|---|
デフォルト: |
ssl_verify_depth 1; |
コンテキスト: |
http , server |
クライアント証明書チェーンの検証の深さを設定します。
エラー処理
ngx_http_ssl_module
モジュールは幾つかの標準的ではないエラーコードをサポートしています。それによりerror_pageディレクティブを使ってリダイレクトに使うことができます。
- 495
- クライアント証明書の検証の間にエラーが発生した;
- 496
- クライアントが要求された証明書を提示しなかった;
- 497
- 通常のリクエストがHTTPSポートに送信された。
リダイレクトは、リクエストが完全にパースされて $request_uri
, $uri
, $args
とその他の変数が利用可能になったあとで、起きます。
埋め込み変数
ngx_http_ssl_module
モジュールは幾つかの埋め込み変数をサポートします:
$ssl_cipher
- SSL接続を確立するために使われたcipherの文字を返します;
$ssl_ciphers
-
クライアントによってサポートされるcipherのリストを返します (1.11.7)。良く知られたcipherは名前でリスト化され、良く知られていないものは16進数で示されます。例えば:
AES128-SHA:AES256-SHA:0x00ff
OpenSSLバージョン 1.0.2以上を使う場合のみ、変数が完全にサポートされます。古いバージョンを使う場合、変数は新しいセッションについてのみ利用可能で、良く知られたcipherのみリスト化されます。
$ssl_client_cert
- SSL接続を確立するために使われたPEM形式のクライアント証明書を返します。それぞれの行は最初にtab文字があることを期待されます; これは proxy_set_header ディレクティブの中で使われる事を意図しています;
$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
", "FAILED
reason
"、証明書が存在しない場合は"NONE
";バージョン 1.11.7 以前は、"
FAILED
"の結果はreason
文字列を含んでいませんでした。 $ssl_curves
-
クライアントによってサポートされるcurveのリストを返します (1.11.7)。良く知られたcurveは名前でリスト化され、良く知られていないものは16進数で示されます。例えば:
0x001d:prime256v1:secp521r1:secp384r1
OpenSSLバージョン 1.0.2以上を使う場合のみ、変数がサポートされます。古いバージョンを使う場合は、変数の値は空文字になるでしょう。
新しいセッションに対してのみ変数が利用可能です。
$ssl_protocol
- 確立されたSSL接続のプロトコルを返します;
$ssl_server_name
- SNI (1.7.0)を使ってリクエストされたサーバ名を返します;
$ssl_session_id
- 確立されたSSL接続のセッション識別子を返します;
$ssl_session_reused
-
SSLセッションが再利用された場合は"
r
"を、そうでなければ".
"を返します(1.5.11)。