FAQ

Page Discussion Edit History

NginxHttpSslModule

Contents

Edit section: Synopsis Synopsis

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) until version 0.8.7+
  • 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.

Since 0.7.14 it is preferred to enable SSL using he `ssl` parameter of the `listen` directive: 

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

Edit section: Generate Certificates 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

Edit section: Using Wildcard certificates with multiple servers 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 this configuration it is better to place a certificate file with several names and its private key file at the http level of configuration to inherit their single memory copy in all servers: 

ssl_certificate      common.crt;
ssl_certificate_key  common.key;
 
server {
  listen           80;
  server_name      www.nginx.org;
  ...
}
 
server {
  listen           443 default ssl;
  server_name      secure.nginx.org;
  ...
}
 
server {
  listen           80;
  listen           443;
  server_name      images.nginx.org;
  ...
}

Edit section: Directives Directives

Edit section: ssl ssl

syntax: ssl [on|off]

default: ssl off

context: main, server

Enables HTTPS for a server.

Edit section: ssl_certificate 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.

Edit section: ssl_certificate_key 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.

Edit section: ssl_client_certificate 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.

Edit section: ssl_dhparam 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.

Edit section: ssl_ciphers 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_ciphers  ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;

Complete list can be looked with the following command: 

openssl ciphers

Edit section: ssl_crl 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.

Edit section: ssl_prefer_server_ciphers 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.

Edit section: ssl_protocols ssl_protocols

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

default: ssl_protocols SSLv2 SSLv3 TLSv1

context: main, server

Directive enables the protocols indicated.

Edit section: ssl_verify_client ssl_verify_client

syntax: ssl_verify_client on|off|optional

default: ssl_verify_client off

context: main, server

Directive enables verifying client certificates. Parameter 'optional' checks a client certificate if it was offered. (Was 'ask' before 0.8.7 and 0.7.63)

Edit section: ssl_verify_depth 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.

Edit section: ssl_session_cache 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.

Before 0.8.34 this must not be set to none or off if ssl_verify_client is set to 'on' or 'optional'

Edit section: ssl_session_timeout 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.

Edit section: ssl_engine 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.

Edit section: Built-in variables 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_session_id at least since version 0.8.20
  • $ssl_client_cert
  • $ssl_client_raw_cert
  • $ssl_client_verify "SUCCESS" if client certificate was verified

Edit section: Nonstandard error codes 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 dismantled and are accessible via variables such as $request_uri, $uri, $arg and others.

Edit section: References References

Original Documentation Implementing an actual SSL Certificate SSL Memory Fragmentation and new default status for ssl_session_cache

Retrieved from "http://wiki.nginx.org/NginxHttpSslModule"