HttpSslModule

WARNING: this article is obsoleted. Please refer to http://nginx.org/en/docs/ for the latest official documentation.

= Synopsis = This module enables HTTPS support.

It supports checking client certificates with two limitations:


 * it's not possible to assign a Certificate Revocation List for Nginx versions below 0.8.7.
 * if you have a chain of certificates &mdash; by having intermediate certificates between the server certificate and the CA root certificate &mdash; they're not specified separately like you would do for Apache. Instead you'll need to concatenate all the certificates, starting with the server certificate, and going deeper in the chain running through all the intermediate certificates. This can be done with "cat chain.crt >> mysite.com.crt" on the command line. Once this is done there's no further use for all the intermediate certificates in what Nginx is concerned. You'll indicate in the Nginx configuration the file with all the (concatenated) certificates.

By default the module is not built, it is necessary to state it explicitly: give the --with-http_ssl_module parameter to ./configure. Building this module requires the OpenSSL library and respective include files; quite often the library and include files live in separate packages in your platform, the later being named like libssl-dev or similar.

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 a chain of certificates, just append the extra certificates to your .crt file (cert.pem in the example). The server certificate needs to be the first on the file, otherwise you'll get a mismatch between private and public keys.

Since Nginx version 0.7.14 the preferred way of enabling SSL is by using the `ssl` parameter of the `listen` directive: server { listen 443 default_server ssl; ssl_certificate     /usr/local/nginx/conf/cert.pem; ssl_certificate_key /usr/local/nginx/conf/cert.key; ... }

Generate Certificates
To generate private (dummy) certificates you can perform the following list of openssl commands.

First change directory to where you want to create the certificate and private key, for example: $ cd /usr/local/nginx/conf Now create the server private key: $ openssl genrsa -out server.key 2048 You can also create a private key with a passphrase, but you will need to enter it every time you start nginx: $ openssl genrsa -des3 -out server.key 2048 Create the Certificate Signing Request (CSR): $ openssl req -new -key server.key -out server.csr Finally sign the certificate using the above private key and CSR: $ openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt

Update Nginx configuration by including the newly signed certificate and private key:

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 we're ready to access the above host using:

https://YOUR_DOMAINNAME_HERE

Using Wildcard certificates with multiple servers
In some instances you may wish to provide a number of secure subdomains amongst unsecured ones, and possibly share resources across both HTTP and HTTPS subdomains. To do this one would require a wildcard subdomain, for example *.nginx.org. An example configuration follows which shows how to configure a standard www subdomain, a secured subdomain, and share images across both subdomains using a third.

When using a configuration like this it's more efficient memory wise to place the certificate file containing the certificate(s) for all domain names and the corresponding private key file directives in a http context, such that it's inherited by all active servers/virtual hosts: ssl_certificate     common.crt; ssl_certificate_key common.key;

server { listen          80; server_name     www.nginx.org; ... }

server { listen          443 default_server ssl; server_name     secure.nginx.org; ... }

server { listen          80; listen          443; server_name     images.nginx.org; ... }

= Directives =

ssl


Enables HTTPS for a server. (Note that since nginx version 0.7.14, the standard way to enable SSL is through the listen directive.)

ssl_certificate


This directive specifies the file containing the certificate, in PEM format, for this virtual host. This file can contain also other certificates and the server private key. Since version 0.6.7 the file path is relative to the directory where nginx main configuration file, nginx.conf, resides.

ssl_certificate_key


This directive specifies the file containing the private key, in PEM format, for this virtual host. Since version 0.6.7 the file path is relative to the directory where nginx main configuration file, nginx.conf, resides.

ssl_ciphers


This directive describes the list of cipher suites the server supports for establishing a secure connection. Cipher suites are specified in the OpenSSL cipherlist format, for example:

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

Since nginx version 1.0.5, the default ciphers are: ssl_ciphers HIGH:!aNULL:!MD5;

The complete cipherlist supported by the currently installed version of OpenSSL in your platform can be obtained by issuing the command: openssl ciphers

ssl_client_certificate


This directive specifies the file containing the CA (root) certificate, in PEM format, that is used for validating client certificates.

ssl_crl


This directive, introduced in Nginx version 0.8.7, specifies the filename of a Certificate Revocation List, in PEM format, which is used to check the revocation status of certificates.

ssl_dhparam


This directive specifies a file containing Diffie-Hellman key agreement protocol cryptographic parameters, in PEM format, utilized for exchanging session keys between server and client.

ssl_prefer_server_ciphers


The server requires that the cipher suite list for protocols SSLv3 and TLSv1 are to be preferred over the client supported cipher suite list.

ssl_protocols


This directive enables the protocol versions specified.

ssl_verify_client


This directive enables the verification of the client identity. Parameter 'optional' checks the client identity using its certificate in case it was made available to the server. (Was 'ask' before 0.8.7 and 0.7.63