HttpSSL
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)
- 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.
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
指令
ssl
syntax: ssl [on|off]
default: ssl off
context: main, server
Enables HTTPS for a server.
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.
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.
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.
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.
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_ciphersALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;
Complete list can be looked with the following command:
openssl ciphers
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.
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.
ssl_protocols
syntax: ssl_protocols [SSLv2] [SSLv3] [TLSv1]
default: ssl_protocols SSLv2 SSLv3 TLSv1
context: main, server
Directive enables the protocols indicated.
ssl_verify_client
syntax: ssl_verify_client on|off|ask
default: ssl_verify_client off
context: main, server
Directive enables verifying client certificates. Parameter 'ask' checks a client certificate if it was offered.
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.
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.
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.
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. 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_engine
syntax: ssl_engine
This allows specifying the OpenSSL engine to use, like Padlock for example. It requires a more recent version of OpenSSL.
References
Original Documentation SSL Memory Fragmentation and new default status for ssl_session_cache