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.
