ngx_mail_ssl_moduleモジュール

設定例
ディレクティブ
     ssl
     ssl_certificate
     ssl_certificate_key
     ssl_ciphers
     ssl_client_certificate
     ssl_crl
     ssl_dhparam
     ssl_ecdh_curve
     ssl_password_file
     ssl_prefer_server_ciphers
     ssl_protocols
     ssl_session_cache
     ssl_session_ticket_key
     ssl_session_tickets
     ssl_session_timeout
     ssl_trusted_certificate
     ssl_verify_client
     ssl_verify_depth
     starttls

ngx_mail_ssl_module モジュールは、メールプロキシサーバがSSL/TLSプロトコルで動作するために必要なサポートを提供します。

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

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

設定例

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

worker_processes auto;

mail {

    ...

    server {
        listen              993 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;

        ...
    }

ディレクティブ

構文: ssl on | off;
デフォルト:
ssl off;
コンテキスト: mail, server

指定されたサーバのためのSSL/TLSプロトコルを有効にします。

構文: ssl_certificate file;
デフォルト: -
コンテキスト: mail, server

指定されたサーバのためのPEM形式の証明書のファイルを指定します。中間証明書はプライマリ証明書に追加して指定されなければなりません。中間証明書は次の順番で同じファイルで指定されなければなりません: プリイマリ証明書が最初に来て、次に中間証明書がきます。PEM形式の秘密鍵が同じファイルにあるかも知れません。

バージョン 1.11.0 から、このディレクティブは異なる種類の証明書、例えばRSAとECDSA、をロードするために複数回指定することができます。

server {
    listen              993 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つの証明書チェーンだけを使うことができます。

構文: ssl_certificate_key file;
デフォルト: -
コンテキスト: mail, server

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

engine:name:id の値は file の代わりに指定することができ(1.7.9)、 特定のOpenSSLのnameの特定の id と一緒に秘密鍵を取り付けます。

構文: ssl_ciphers ciphers;
デフォルト:
ssl_ciphers HIGH:!aNULL:!MD5;
コンテキスト: mail, server

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

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

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

以前のバージョンのnginxはデフォルトでdifferent ciphers を使っていました。

構文: ssl_client_certificate file;
デフォルト: -
コンテキスト: mail, server

このディレクティブはバージョン1.7.11から導入されました。

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

証明書のリストはクライアントに送信されるでしょう。これが望ましく無い場合、ssl_trusted_certificate ディレクティブを使うことができます。

構文: ssl_crl file;
デフォルト: -
コンテキスト: mail, server

このディレクティブはバージョン1.7.11から導入されました。

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

構文: ssl_dhparam file;
デフォルト: -
コンテキスト: mail, server

このディレクティブはバージョン0.7.2から導入されました。

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

構文: ssl_ecdh_curve curve;
デフォルト:
ssl_ecdh_curve auto;
コンテキスト: mail, 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 file;
デフォルト: -
コンテキスト: mail, server

このディレクティブはバージョン1.7.3から導入されました。

secret keysのためのそれぞれのパスフレーズが一行に指定されているfileを指定します。パスフレーズはキーがロードされる時に順番に試されます。

例:

mail {
    ssl_password_file /etc/keys/global.pass;
    ...

    server {
        server_name mail1.example.com;
        ssl_certificate_key /etc/keys/first.key;
    }

    server {
        server_name mail2.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 on | off;
デフォルト:
ssl_prefer_server_ciphers off;
コンテキスト: mail, server

SSLv3とTLSプロトコルが使われる時に、サーバのcipherをクライアントのcipherよりも選ぶように指定します。

構文: ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2];
デフォルト:
ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
コンテキスト: mail, server

指定されたプロトコルを有効にします。バージョン1.0.1以上のOpenSSLライブラリが使われたときにのみ、 TLSv1.1TLSv1.2 パラメータは動作するでしょう。

バージョン 1.1.13と1.0.12からTLSv1.1 and TLSv1.2 パラメータがサポートされています。そのため古いnginxバージョンではOpenSSLのバージョン 1.0.1以上が使われます。これらのプロトコルは動作しますが、無効にすることができません。

構文: ssl_session_cache off | none | [builtin[:size]] [shared:name:size];
デフォルト:
ssl_session_cache none;
コンテキスト: mail, 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 file;
デフォルト: -
コンテキスト: mail, 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 on | off;
デフォルト:
ssl_session_tickets on;
コンテキスト: mail, server

このディレクティブはバージョン1.5.9から導入されました。

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

構文: ssl_session_timeout time;
デフォルト:
ssl_session_timeout 5m;
コンテキスト: mail, server

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

構文: ssl_trusted_certificate file;
デフォルト: -
コンテキスト: mail, server

このディレクティブはバージョン1.7.11から導入されました。

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

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

構文: ssl_verify_client on | off | optional | optional_no_ca;
デフォルト:
ssl_verify_client off;
コンテキスト: mail, server

このディレクティブはバージョン1.7.11から導入されました。

クライアントの証明書の検証を有効にする。検証結果は authentication リクエストの"Auth-SSL-Verify"ヘッダの中で渡されます。

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

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

構文: ssl_verify_depth number;
デフォルト:
ssl_verify_depth 1;
コンテキスト: mail, server

このディレクティブはバージョン1.7.11から導入されました。

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

構文: starttls on | off | only;
デフォルト:
starttls off;
コンテキスト: mail, server

on
POP3のためのSTLS コマンドの利用と、IMAPのためのSTARTTLSコマンドの利用を許可します;
off
STLSSTARTTLSコマンドの利用を禁止します;
only
予備のTLS推移を要求します。

TOP
inserted by FC2 system