Nginx - Additional Modules, SSL and Security

Nginx provides secure HTTP functionalities through the SSL module but also offers an extra module called Secure Link that helps you protect your website and visitors in a totally different way.

SSL

The SSL module enables HTTPS support, HTTP over SSL/TLS in particular. It gives you the possibility to serve secure websites by providing a certificate, a certificate key, and other parameters defined with the following directives:

This module is not included in the default Nginx build.

ssl

Context: http, server

Enables HTTPS for the specified server. This directive is the equivalent of listen 443 ssl or listen port ssl more generally.

Syntax: on or off

Default: ssl off;

ssl_certificate

Context: http, server

Sets the path of the PEM certificate.

Syntax: File path

ssl_certificate_key

Context: http, server

Sets the path of the PEM secret key file.

Syntax: File path

ssl_client_certificate

Context: http, server

Sets the path of the client PEM certificate.

Syntax: File path

ssl_crl

Context: http, server

Orders Nginx to load a CRL (Certificate Revocation List) file, which allows checking the revocation status of certificates.

ssl_dhparam

Context: http, server

Sets the path of the Diffie-Hellman parameters file.

Syntax: File path.

ssl_protocols

Context: http, server

Specifies the protocol that should be employed.

Syntax: ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2];

Default: ssl_protocols SSLv2 SSLv3 TLSv1;

ssl_ciphers

Context: http, server

Specifies the ciphers that should be employed. The list of available ciphers can be obtained running the following command from the shell: openssl ciphers.

Syntax: ssl_ciphers cipher1[:cipher2…];

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

ssl_prefer_server_ciphers

Context: http, server

Specifies whether server ciphers should be preferred over client ciphers.

Syntax: on or off

Default: off

ssl_verify_client

Context: http, server

Enables verifying certificates transmitted by the client and sets the result in the $ssl_client_verify. The optional_no_ca value verifies the certificate if there is one, but does not require it to be signed by a trusted CA certificate.

Syntax: on | off | optional | optional_no_ca

Default: off

ssl_session_cache

Context: http, server

Configures the cache for SSL sessions.

Syntax: off, none, builtin:size or shared:name:size

Default: off (disables SSL sessions)

ssl_session_timeout

Context: http, server

When SSL sessions are enabled, this directive defines the timeout for using session data.

Syntax: Time value

Default: 5 minutes

Additionally, the following variables are made available:

• $ssl_cipher: Indicates the cipher used for the current request
• $ssl_client_serial: Indicates the serial number of the client certificate
• $ssl_client_s_dn and $ssl_client_i_dn: Indicates the value of the Subject and Issuer DN of the client certificate
• $ssl_protocol: Indicates the protocol at use for the current request
• $ssl_client_cert and $ssl_client_raw_cert: Returns client certificate data, which is raw data for the second variable
• $ssl_client_verify: Set to SUCCESS if the client certificate was successfully verified
• $ssl_session_id: Allows you to retrieve the ID of an SSL session

Setting Up an SSL Certificate

Although the SSL module offers a lot of possibilities, in most cases only a couple of directives are actually useful for setting up a secure website. This guide will help you configure Nginx to use an SSL certificate for your website (in the example, your website is identified by secure.website.com). Before doing so, ensure that you already have the following elements at your disposal:

• A .key file generated with the following command: openssl genrsa -out secure.website.com.key 1024 (other encryption levels work too).
• A .csr file generated with the following command: openssl req -new -key secure.website.com.key -out secure.website.com.csr.
• Your website certificate file, as issued by the Certificate Authority, for example, secure.website.com.crt. (Note: In order to obtain a certificate from the CA, you will need to provide your .csr file.)
• The CA certificate file as issued by the CA (for example, gd_bundle.crt if you purchased your certificate from GoDaddy.com).

The first step is to merge your website certificate and the CA certificate together with the following command:

cat secure.website.com.crt gd_bundle.crt > combined.crt

You are then ready to configure Nginx to serve secure content:

server {

　　listen 443;

　　server_name secure.website.com;

　　ssl on;

　　ssl_certificate /path/to/combined.crt;

　　ssl_certificate_key /path/to/secure.website.com.key;

　　[…]

}

Secure Link

Totally independent from the SSL module, Secure link provides a basic protection by checking the presence of a specific hash in the URL before allowing the user to access a resource:

location /downloads/ {

　　secure_link_md5 "secret";

　　secure_link $arg_hash,$arg_expires;

　　if ($secure_link = "") {

　　　　return 403;

　　}

}

With such a configuration, documents in the /downloads/ folder must be accessed via a URL containing a query string parameter hash=XXX (note the $arg_hash in the example), where XXX is the MD5 hash of the secret you defined through the secure_link_md5 directive. The second argument of the secure_link directive is a UNIX timestamp defining the expiration date. The $secure_link variable is empty if the URI does not contain the proper hash or if the date has expired. Otherwise, it is set to 1.

This module is not included in the default Nginx build.