Module ngx_stream_ssl_module

The ngx_stream_ssl_module module (1.9.0) provides the necessary support for a stream proxy server to work with the SSL/TLS protocol. This module is not built by default, it should be enabled with the --with-stream_ssl_module configuration parameter.

To reduce the processor load, it is recommended to

• set the number of worker processes equal to the number of processors,
• enable the shared session cache,
• disable the built-in session cache,
• and possibly increase the session lifetime (by default, 5 minutes):

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;

        ...
    }

Specifies a file with the certificate in the PEM format for the given server. If intermediate certificates should be specified in addition to a primary certificate, they should be specified in the same file in the following order: the primary certificate comes first, then the intermediate certificates. A secret key in the PEM format may be placed in the same file.

Specifies a file with the secret key in the PEM format for the given server.

The value engine:name:id can be specified instead of the file, which loads a secret key with a specified id from the OpenSSL engine name.

ssl_ciphers HIGH:!aNULL:!MD5;

Specifies the enabled ciphers. The ciphers are specified in the format understood by the OpenSSL library, for example:

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

The full list can be viewed using the “openssl ciphers” command.

Specifies a file with DH parameters for EDH ciphers.

ssl_ecdh_curve prime256v1;

Specifies a curve for ECDHE ciphers.

ssl_handshake_timeout 60s;

Specifies a timeout for the SSL handshake to complete.

Specifies a file with passphrases for secret keys where each passphrase is specified on a separate line. Passphrases are tried in turn when loading the key.

Example:

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;

Specifies that server ciphers should be preferred over client ciphers when the SSLv3 and TLS protocols are used.

ssl_protocols TLSv1 TLSv1.1 TLSv1.2;

Enables the specified protocols. The TLSv1.1 and TLSv1.2 parameters work only when the OpenSSL library of version 1.0.1 or higher is used.

ssl_session_cache none;

Sets the types and sizes of caches that store session parameters. A cache can be of any of the following types:

off

the use of a session cache is strictly prohibited: nginx explicitly tells a client that sessions may not be reused.

none

the use of a session cache is gently disallowed: nginx tells a client that sessions may be reused, but does not actually store session parameters in the cache.

builtin

a cache built in OpenSSL; used by one worker process only. The cache size is specified in sessions. If size is not given, it is equal to 20480 sessions. Use of the built-in cache can cause memory fragmentation.

shared

a cache shared between all worker processes. The cache size is specified in bytes; one megabyte can store about 4000 sessions. Each shared cache should have an arbitrary name. A cache with the same name can be used in several servers.

Both cache types can be used simultaneously, for example:

ssl_session_cache builtin:1000 shared:SSL:10m;

but using only shared cache without the built-in cache should be more efficient.

Sets a file with the secret key used to encrypt and decrypt TLS session tickets. The directive is necessary if the same key has to be shared between multiple servers. By default, a randomly generated key is used.

If several keys are specified, only the first key is used to encrypt TLS session tickets. This allows configuring key rotation, for example:

ssl_session_ticket_key current.key;
ssl_session_ticket_key previous.key;

The file must contain 48 bytes of random data and can be created using the following command:

openssl rand 48 > ticket.key

ssl_session_tickets on;

Enables or disables session resumption through TLS session tickets.

ssl_session_timeout 5m;

Specifies a time during which a client may reuse the session parameters stored in a cache.