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 ssl;
        keepalive_timeout   70;

        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.

It is recommended to use the ssl parameter of the listen directive instead of this directive.

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 trusted CA certificates in the PEM format used to verify client certificates and OCSP responses if is enabled.

The list of certificates will be sent to clients. If this is not desired, the directive can be used.

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_stapling off;

This directive appeared in version 1.3.7.

Enables or disables stapling of OCSP responses by the server. Example:

ssl_stapling on;
resolver 192.0.2.1;

For the OCSP stapling to work, the certificate of the issuer of the server certificate should be known. If the file does not contain intermediate certificates, the certificate of the issuer of the server certificate should be present in the file.

The resolver directive should also be specified to allow for a resolution of an OCSP responder hostname.

This directive appeared in version 1.3.7.

When set, the stapled OCSP response will be taken from the specified file instead of querying the OCSP responder specified in the server certificate.

The file should be in the DER format as produced by the “openssl ocsp” command.

This directive appeared in version 1.3.7.

Overrides the URL of OCSP responder specified in the “Authority Information Access” certificate extension.

Only “http://” OCSP responders are supported:

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

ssl_stapling_verify off;

This directive appeared in version 1.3.7.

Enables or disables verification of OCSP responses by the server.

For verification to work, the certificate of the issuer of the server certificate, the root certificate, and all intermediate certificates should be configured as trusted using the directive.

This directive appeared in version 1.3.7.

Specifies a file with trusted CA certificates in the PEM format used to verify client certificates and OCSP responses if is enabled.

In contrast to , the list of these certificates will not be sent to clients.

ssl_verify_client off;

Enables verification of client certificates. The result of verification is stored in the $ssl_client_verify variable.

The optional parameter (0.8.7+) requests the client certificate, and if certificate was present, verifies it.

The optional_no_ca parameter (1.3.8, 1.2.5) requests the client certificate but does not require it to be signed by a trusted CA certificate. This is intended for the use in cases where actual certificate verification is performed by a service that is external to nginx. The contents of a certificate is made available through the $ssl_client_cert 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.