FAQ

Page Discussion History

Difference between revisions of "HttpSslModule"

(Directives)
m (NOINDEX added)
 
(8 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 +
__NOINDEX__
 +
<span style="color:red">WARNING: this article is obsoleted. Please refer to http://nginx.org/en/docs/ for the latest official documentation.</span>
 +
 
= Synopsis =
 
= Synopsis =
 
This module enables HTTPS support.
 
This module enables HTTPS support.
Line 44: Line 47:
 
$ cd /usr/local/nginx/conf
 
$ cd /usr/local/nginx/conf
 
</pre>
 
</pre>
Now create the server private key, you'll be asked for a passphrase:
+
Now create the server private key:
 
<pre>
 
<pre>
$ openssl genrsa -des3 -out server.key 1024
+
$ openssl genrsa -out server.key 2048
 
</pre>
 
</pre>
Create the Certificate Signing Request (CSR):
+
You can also create a private key with a passphrase, but you will need to enter it every time you start nginx:
 
<pre>
 
<pre>
$ openssl req -new -key server.key -out server.csr
+
$ openssl genrsa -des3 -out server.key 2048
 
</pre>
 
</pre>
Remove the necessity of entering a passphrase for starting up nginx with SSL using the above private key:
+
Create the Certificate Signing Request (CSR):
 
<pre>
 
<pre>
$ cp server.key server.key.org
+
$ openssl req -new -key server.key -out server.csr
$ openssl rsa -in server.key.org -out server.key
+
 
</pre>
 
</pre>
 
Finally sign the certificate using the above private key and CSR:  
 
Finally sign the certificate using the above private key and CSR:  
Line 111: Line 113:
 
= Directives =
 
= Directives =
 
== ssl ==
 
== ssl ==
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/ngx_http_ssl_module/ssl.txt" />
+
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_ssl_module/ssl.txt" />
  
 
Enables HTTPS for a server.  (Note that since nginx version 0.7.14, the standard way to enable SSL is through the '''[[HttpCoreModule#listen|listen]]''' directive.)
 
Enables HTTPS for a server.  (Note that since nginx version 0.7.14, the standard way to enable SSL is through the '''[[HttpCoreModule#listen|listen]]''' directive.)
  
 
== ssl_certificate ==
 
== ssl_certificate ==
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/ngx_http_ssl_module/ssl_certificate.txt" />
+
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_ssl_module/ssl_certificate.txt" />
  
 
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.
 
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 ==
 
== ssl_certificate_key ==
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/ngx_http_ssl_module/ssl_certificate_key.txt" />
+
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_ssl_module/ssl_certificate_key.txt" />
  
 
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.
 
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_client_certificate ==
 
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/ngx_http_ssl_module/ssl_client_certificate.txt" />
 
 
This directive specifies the file containing the CA (root) certificate, in PEM format, that is used for validating client certificates.
 
 
== ssl_dhparam ==
 
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/ngx_http_ssl_module/ssl_dhparam.txt" />
 
 
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_ciphers ==
 
== ssl_ciphers ==
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/ngx_http_ssl_module/ssl_ciphers.txt" />
+
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_ssl_module/ssl_ciphers.txt" />
  
 
This directive describes the list of cipher suites the server supports for establishing a secure connection. Cipher suites are specified in the [http://openssl.org/docs/apps/ciphers.html OpenSSL] cipherlist format, for example:
 
This directive describes the list of cipher suites the server supports for establishing a secure connection. Cipher suites are specified in the [http://openssl.org/docs/apps/ciphers.html OpenSSL] cipherlist format, for example:
Line 153: Line 145:
 
openssl ciphers
 
openssl ciphers
 
</pre>
 
</pre>
 +
 +
== ssl_client_certificate ==
 +
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_ssl_module/ssl_client_certificate.txt" />
 +
 +
This directive specifies the file containing the CA (root) certificate, in PEM format, that is used for validating client certificates.
  
 
== ssl_crl ==
 
== ssl_crl ==
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/ngx_http_ssl_module/ssl_crl.txt" />
+
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_ssl_module/ssl_crl.txt" />
  
 
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.
 
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 ==
 +
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_ssl_module/ssl_dhparam.txt" />
 +
 +
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 ==
 
== ssl_prefer_server_ciphers ==
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/ngx_http_ssl_module/ssl_prefer_server_ciphers.txt" />
+
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_ssl_module/ssl_prefer_server_ciphers.txt" />
  
 
The server requires that the cipher suite list for protocols SSLv3 and TLSv1 are to be preferred over the client supported cipher suite list.
 
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 ==
 
== ssl_protocols ==
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/ngx_http_ssl_module/ssl_protocols.txt" />
+
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_ssl_module/ssl_protocols.txt" />
  
 
This directive enables the protocol versions specified.
 
This directive enables the protocol versions specified.
  
 
== ssl_verify_client ==
 
== ssl_verify_client ==
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/ngx_http_ssl_module/ssl_verify_client.txt" />
+
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_ssl_module/ssl_verify_client.txt" />
 
+
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)
+
 
+
== ssl_verify_depth ==
+
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/ngx_http_ssl_module/ssl_verify_depth.txt" />
+
 
+
This directive sets how deep the server should go in the client provided certificate chain in order to verify the client identity.
+
 
+
== ssl_session_cache ==
+
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/ngx_http_ssl_module/ssl_session_cache.txt" />
+
 
+
The directive sets the types and sizes of caches to store the SSL sessions.<BR>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 the cache is assigned in bytes: 1 MB cache can contain roughly 4000 sessions. Each shared cache must be given an arbitrary name. A shared cache with a given name can be used in several virtual hosts.
+
It's possible to use both types of cache &mdash; builtin and shared &mdash; simultaneously, for example:
+
 
+
<pre>
+
  ssl_session_cache  builtin:1000  shared:SSL:10m;
+
</pre>
+
Bear in mind however, that using only shared cache, i.e., without builtin, should be more effective.
+
 
+
For Nginx versions below 0.8.34 this directive shouldn't be set to 'none' or 'off' if ssl_verify_client is set to 'on' or 'optional'.
+
 
+
* Note that for session resumption to work you'll need to have, at least, the server configured as '''default''' for the SSL socket. Like this:
+
<geshi lang="nginx">
+
listen [::]:443 ssl default_server;
+
</geshi>
+
This is so because session resumption happens before any TLS extensions are enabled, namely Server Name Identification (SNI). The ClientHello message requests a session ID from a given IP address (server). For that to work the default server setting is '''required'''.
+
 
+
A '''preferred''' approach is to move the <code>ssl_session_cache</code> directive to the <code>http</code> context. The (minor) downside is that all configured virtual hosts get the '''same''' SSL cache settings.
+
 
+
== ssl_session_timeout ==
+
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/ngx_http_ssl_module/ssl_session_timeout.txt" />
+
 
+
This directive defines the maximum time during which the client can re-use the previously negotiated cryptographic parameters of the secure session that is stored in the SSL cache.
+
 
+
== ssl_engine ==
+
'''syntax:''' ''ssl_engine''
+
 
+
This allows specifying the OpenSSL engine to use, like PadLock, for example. It requires a recent version of OpenSSL. To verify if the OpenSSL version installed in your platform supports this, issue the command:
+
<pre>
+
openssl engine
+
</pre>
+
On a Debian testing with OpenSSL version 0.9.8o from 01 Jun 2010 it returns:
+
<pre>
+
$ openssl engine
+
(padlock) VIA PadLock (no-RNG, no-ACE)
+
(dynamic) Dynamic engine loading support
+
</pre>
+
 
+
= Built-in variables =
+
 
+
Module ngx_http_ssl_module supports the following built-in variables:
+
 
+
* $ssl_cipher returns the cipher suite being used for the currently established SSL/TLS connection
+
* $ssl_client_serial returns the serial number of the client certificate for the currently established SSL/TLS connection &mdash; if applicable, i.e., if client authentication is activated in the connection
+
* $ssl_client_s_dn returns the subject Distinguished Name (DN) of the client certificate for the currently established SSL/TLS connection &mdash; if applicable, i.e., if client authentication is activated in the connection
+
* $ssl_client_i_dn returns the issuer DN of the client certificate for the currently established SSL/TLS connection &mdash; if applicable, i.e., if client authentication is activated in the connection
+
* $ssl_protocol returns the protocol of the currently established SSL/TLS connection &mdash; depending on the configuration and client available options it's one of SSLv2, SSLv3 or TLSv1
+
* $ssl_session_id the Session ID of the established secure connection &mdash; requires Nginx version greater or equal to 0.8.20
+
* $ssl_client_cert
+
* $ssl_client_raw_cert
+
* $ssl_client_verify takes the value "SUCCESS" when the client certificate is successfully verified
+
 
+
= Nonstandard error codes =
+
 
+
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 "disassembled" and it's components are accessible via variables such as $request_uri, $uri, $arg and more.
+
  
= References =
+
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
* [http://nginx.org/en/docs/http/ngx_http_ssl_module.html Original Documentation]
+
* [http://kbeezie.com/view/free-ssl-with-nginx/ Implementing an actual SSL Certificate]
+
* [http://marc.info/?t=120127289900027 SSL Memory Fragmentation and new default status for ssl_session_cache]
+

Latest revision as of 08:09, 10 April 2014

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

Contents

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 — by having intermediate certificates between the server certificate and the CA root certificate — 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

Syntax: ssl on | off
Default: off
Context: http
server
Reference: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

Syntax: ssl_certificate file
Default:
Context: http
server
Reference: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

Syntax: ssl_certificate_key file
Default:
Context: http
server
Reference: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

Syntax: ssl_ciphers ciphers
Default: HIGH:!aNULL:!MD5
Context: http
server
Reference: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

Syntax: ssl_client_certificate file
Default:
Context: http
server
Reference: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

Syntax: ssl_crl file
Default:
Context: http
server
Appeared in: 0.8.7
Reference: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

Syntax: ssl_dhparam file
Default:
Context: http
server
Appeared in: 0.7.2
Reference: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

Syntax: ssl_prefer_server_ciphers on | off
Default: off
Context: http
server
Reference: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

Syntax: ssl_protocols [ SSLv2 ] [ SSLv3 ] [ TLSv1 ] [ TLSv1.1 ] [ TLSv1.2 ]
Default: SSLv3 TLSv1 TLSv1.1 TLSv1.2
Context: http
server
Reference:ssl_protocols


This directive enables the protocol versions specified.

ssl_verify_client

Syntax: ssl_verify_client on | off | optional | optional_no_ca
Default: off
Context: http
server
Reference: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