HttpSSL

This module enables HTTPS support.

It supports checking client certificates with two limitations:

  • it is not possible to assign the list of the abolished certificates (revocation lists)
  • if you have a chain certificate file (sometimes called an intermediate certificate) you don't specify it separately like you do in Apache. Instead you need to add the information from the chain cert to the end of your main certificate file. This can be done by typing "cat chain.crt >> mysite.com.crt" on the command line. Once that is done you won't use the chain cert file for anything else, you just point Nginx to the main certificate file.

By default the module is not built, it is necessary to specify that it be built with with the --with-http_ssl_module parameter to ./configure. Building this module requires the OpenSSL libraries and include-files, often are the necessary files in separate packages.

The following is an example configuration, to reduce the CPU load it is recommended to run one worker process only and to enable keep-alive connections:

worker_processes 1;
http {

  server {
    listen               443;
    ssl                  on;
    ssl_certificate      /usr/local/nginx/conf/cert.pem;
    ssl_certificate_key  /usr/local/nginx/conf/cert.key;
    keepalive_timeout    70;
  }

}

When using chain certificates, just append the extra certificates into your .crt file (cert.pem in the example). Your own certificate needs to be on top of the file, otherwise key get a mismatch with the key.

Generate Certificates

To generate dummy certficates you can do this steps:

$ cd /usr/local/nginx/conf
$ openssl genrsa -des3 -out server.key 1024
$ openssl req -new -key server.key -out server.csr
$ cp server.key server.key.org
$ openssl rsa -in server.key.org -out server.key
$ openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt

Configure the new certificate into nginx.conf:

server {

    server_name YOUR_DOMAINNAME_HERE;
    listen 443;
    ssl on;
    ssl_certificate /usr/local/nginx/conf/server.crt;
    ssl_certificate_key /usr/local/nginx/conf/server.key;

}

Restart Nginx.

Now all ready to access using:

https://YOUR_DOMAINNAME_HERE

鎸囦护

ssl

syntax:*ssl [on|off]*

default:*ssl off*

context:*main, server*

Enables HTTPS for a server.

ssl_certificate

syntax:*ssl_certificate file*

default:*ssl_certificate cert.pem*

context:*main, server*

Indicates file with the certificate in PEM format for this virtual server. The same file can contain other certificates, and also secret key in PEM format. Since version 0.6.7 the file path is relative to directory of nginx configuration file nginx.conf, but not to nginx prefix directory.

ssl_certificate_key

syntax:*ssl_certificate_key file*

default:*ssl_certificate_key cert.pem*

context:*main, server*

Indicates file with the secret key in PEM format for this virtual server. Since version 0.6.7 the filename path is relative to directory of nginx configuration file nginx.conf, but not to nginx prefix directory.

ssl_client_certificate

syntax:*ssl_client_certificate file*

default:*none*

context:*main, server*

Indicates file with certificates CA in PEM format, utilized for checking the client certificates.

ssl_dhparam

syntax:*ssl_dhparam file*

default:*none*

context:*main, server*

Indicates file with Diffie-Hellman parameters in PEM format, utilized for negotiating TLS session keys.

ssl_ciphers

syntax:*ssl_ciphers file*

default:*ssl_ciphers ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP*

context:*main, server*

Directive describes the permitted ciphers. Ciphers are assigned in the formats supported by OpenSSL, for example:

ssl_ciphersALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;

Complete list can be looked with the following command:


openssl ciphers

ssl_crl

syntax:*ssl_crl file*

default:*none*

context:*http, server*

This directive (0.8.7+) specifies a file with the revoked certificates (CRL) in the PEM, which is used to check for client certificates.

ssl_prefer_server_ciphers

syntax:*ssl_prefer_server_ciphers [on|off]*

default:*ssl_prefer_server_ciphers off*

context:*main, server*

Requires protocols SSLv3 and TLSv1 server ciphers be preferred over the client's ciphers.

ssl_protocols

syntax:*ssl_protocols [SSLv2] [SSLv3] [TLSv1]*

default:*ssl_protocols SSLv2 SSLv3 TLSv1*

context:*main, server*

Directive enables the protocols indicated.

ssl_verify_client

syntax:*ssl_verify_client on|off|ask*

default:*ssl_verify_client off*

context:*main, server*

Directive enables verifying client certificates. Parameter 'ask' checks a client certificate if it was offered.

ssl_verify_depth

syntax:*ssl_verify_depth number*

default:*ssl_verify_depth 1*

context:*main, server*

Sets depth checking in the chain of client certificates.

ssl_session_cache

syntax:*ssl_session_cache off|none|builtin:size and/or shared:name:size*

default:*ssl_session_cache off*

context:*main, server*

The directive sets the types and sizes of caches to store the SSL sessions.
The cache types are:

  • off -- Hard off: nginx says explicitly to a client that sessions can not reused.
  • none -- Soft off: nginx says to a client that session can be resued, but nginx actually never reuses them. This is workaround for some mail clients as ssl_session_cache may be used in mail proxy as well as in HTTP server.
  • builtin -- the OpenSSL builtin cache, is used inside one worker process only. The cache size is assigned in the number of the sessions. Note: there appears to be a memory fragmentation issue using this method, please take that into consideration when using this. See "References" below.
  • shared -- the cache is shared between all worker processes. The size of cache is assigned in the bytes, 1 MB cache can contain about 4000 sessions. Each shared cache must have arbitrary name. Cache with the same name can be used in several virtual servers.

It is possible to use both types of cache simultaneously, for example:

  ssl_session_cache  builtin:1000  shared:SSL:10m;

However, the only shared cache usage without that builtin should be more effective.

ssl_session_timeout

syntax:*ssl_session_timeout time*

default:*ssl_session_timeout 5m*

context:*main, server*

Assigns the time during which the client can repeatedly use the parameters of the session, which is stored in the cache.

This module supports several nonstandard error codes which can be used for debugging with the aid of directive error_page:

  • 495 - error checking client certificate
  • 496 - client did not grant the required certificate
  • 497 - normal request was sent to HTTPS

Debugging is done after the request is completely dismantled and are accessible via variables such as $request_uri, $uri, $arg and others. Built-in variables Module ngx_http_ssl_module supports several built-in variables:

  • $ssl_cipher returns the line of those utilized it is cipher for established SSL-connection
  • $ssl_client_serial returns the series number of client certificate for established SSL-connection
  • $ssl_client_s_dn returns line subject DN of client certificate for established SSL-connection
  • $ssl_client_i_dn returns line issuer DN of client certificate for established SSL-connection
  • $ssl_protocol returns the protocol of established SSL-connection

ssl_engine

syntax:*ssl_engine*

This allows specifying the OpenSSL engine to use, like Padlock for example. It requires a more recent version of OpenSSL.

References

Original DocumentationSSL Memory Fragmentation and new default status for ssl_session_cache