Module ngx_http_ssl_module

The ngx_http_ssl_module module provides the necessary support for HTTPS.

This module is not built by default, it should be enabled with the --with-http_ssl_module configuration parameter.

This module requires the OpenSSL library.

Example Configuration

To reduce the processor load it is recommended to

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

worker_processes 2;

http {

    ...

    server {
        listen              443;
        keepalive_timeout   70;

        ssl                 on;
        ssl_protocols       SSLv3 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;

        ...
    }

Directives

ssl off;

Enables the HTTPS protocol for the given virtual server.

Specifies a file with a certificate in the PEM format for the given virtual 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.

It should be kept in mind that due to the HTTPS protocol limitations virtual servers should listen on different IP addresses:

server {
    listen          192.168.1.1:443;
    server_name     one.example.com;
    ssl_certificate /usr/local/nginx/conf/one.example.com.cert;
    ...
}

server {
    listen          192.168.1.2:443;
    server_name     two.example.com;
    ssl_certificate /usr/local/nginx/conf/two.example.com.cert;
    ...
}

otherwise the first server’s certificate will be issued for the second site.

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

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.

The previous versions of nginx used different ciphers by default.

Specifies a file with CA certificates in the PEM format used for client certificate verification.

This directive appeared in version 0.8.7.

Specifies a file with revoked certificates (CRL) in the PEM format, used to client certificate verification.

This directive appeared in version 0.7.2.

Specifies a file with DH parameters for EDH ciphers.

ssl_prefer_server_ciphers off;

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

ssl_protocols SSLv3 TLSv1 TLSv1.1 TLSv1.2;

Enables the specified protocols. The parameters TLSv1.1 and TLSv1.2 work only when using the OpenSSL library version 1.0.1 and higher.

The parameters TLSv1.1 and TLSv1.2 are supported starting from versions 1.1.13 and 1.0.12 so when using OpenSSL version 1.0.1 and higher on older nginx versions these protocols will work but could not be disabled.

ssl_session_cache none;

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

off

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

none

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

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

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 virtual 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.

ssl_session_timeout 5m;

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

ssl_verify_client off;

Enables the client certificate verification. The optional parameter (0.8.7+) requests the client certificate and verifies it if it was present. The result of verification is stored in the $ssl_client_verify variable.

ssl_verify_depth 1;

Sets a verification depth in the client certificates chain.

Error Processing

The ngx_http_ssl_module module supports several non-standard error codes that can be used for redirects using the error_page directive:

495

an error has occurred during the client certificate verification;

496

a client did not present the required certificate;

497

a regular request was sent to the HTTPS port.

A redirection happens after the request was fully parsed and variables such as $request_uri, $uri, $args and others were made available.

Embedded Variables

The ngx_http_ssl_module module supports several embedded variables:

$ssl_cipher

returns the string of ciphers used for an established SSL connection;

$ssl_client_cert

returns the client certificate in the PEM format for an established SSL connection, with each line except the first prepended with the tab character; this is intended for the use in the proxy_set_header directive;

$ssl_client_raw_cert

returns the client certificate in the PEM format for an established SSL connection;

$ssl_client_serial

returns the serial number of the client certificate for an established SSL connection;

$ssl_client_s_dn

returns the “subject DN” string of the client certificate for an established SSL connection;

$ssl_client_i_dn

returns the “issuer DN” string of the client certificate for an established SSL connection;

$ssl_client_verify

returns the result of client certificate verification: “SUCCESS”, “FAILED”, and “NONE” if a certificate was not present;

$ssl_protocol

returns the protocol of an established SSL connection;

$ssl_session_id

returns the session identifier of an established SSL connection.