Module ngx_http_ssl_module
ngx_http_ssl_module
module provides the
necessary support for HTTPS.
This module is not built by default, it should be enabled with the
--with-http_ssl_module
configuration parameter.
This module requires the
OpenSSL
library.
ssl_protocols TLSv1 TLSv1.1 TLSv1.2 TLSv1.3;
ssl_ciphers AES128-SHA:AES256-SHA:RC4-SHA:DES-CBC3-SHA:RC4-MD5;
ssl_certificate /usr/local/nginx/conf/cert.pem;
ssl_certificate_key /usr/local/nginx/conf/cert.key;
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 10m;
This directive was made obsolete in version 1.15.0
and was removed in version 1.25.1.
The
ssl
parameter
of the
listen
directive
should be used instead.
Syntax:
ssl_buffer_size
size
;
This directive appeared in version 1.5.9.
Sets the size of the buffer used for sending data.
By default, the buffer size is 16k, which corresponds to minimal
overhead when sending big responses.
To minimize Time To First Byte it may be beneficial to use smaller values,
for example:
ssl_buffer_size 4k;
Specifies a
file
with the certificate in the PEM format
for the given virtual server.
If intermediate certificates should be specified in addition to a primary
certificate, they should be specified in the same file in the following
order: the primary certificate comes first, then the intermediate certificates.
A secret key in the PEM format may be placed in the same file.
Since version 1.11.0,
this directive can be specified multiple times
to load certificates of different types, for example, RSA and ECDSA:
server {
listen 443 ssl;
server_name example.com;
ssl_certificate example.com.rsa.crt;
ssl_certificate_key example.com.rsa.key;
ssl_certificate example.com.ecdsa.crt;
ssl_certificate_key example.com.ecdsa.key;
Only OpenSSL 1.0.2 or higher supports separate
certificate chains
for different certificates.
With older versions, only one certificate chain can be used.
Since version 1.15.9, variables can be used in the
file
name
when using OpenSSL 1.0.2 or higher:
ssl_certificate $ssl_server_name.crt;
ssl_certificate_key $ssl_server_name.key;
Note that using variables implies that
a certificate will be loaded for each SSL handshake,
and this may have a negative impact on performance.
The value
data
:
$variable
can be specified instead of the
file
(1.15.10),
which loads a certificate from a variable
without using intermediate files.
Note that inappropriate use of this syntax may have its security implications,
such as writing secret key data to
error log
.
It should be kept in mind that due to the HTTPS protocol limitations
for maximum interoperability virtual servers should listen on
different
IP addresses
.
Syntax:
ssl_certificate_key
file
;
engine
:
name
:
id
can be specified instead of the
file
(1.7.9),
which loads a secret key with a specified
id
from the OpenSSL engine
name
.
The value
data
:
$variable
can be specified instead of the
file
(1.15.10),
which loads a secret key from a variable without using intermediate files.
Note that inappropriate use of this syntax may have its security implications,
such as writing secret key data to
error log
.
Since version 1.15.9, variables can be used in the
file
name
when using OpenSSL 1.0.2 or higher.
Syntax:
ssl_ciphers
ciphers
;
Specifies the enabled ciphers.
The ciphers are specified in the format understood by the
OpenSSL library, for example:
ssl_ciphers ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;
The full list can be viewed using the
“
openssl ciphers
” command.
The previous versions of nginx used
different
ciphers by default.
Specifies a
file
with trusted CA certificates in the PEM format
used to
verify
client certificates and
OCSP responses if
ssl_stapling
is enabled.
The list of certificates will be sent to clients.
If this is not desired, the
ssl_trusted_certificate
directive can be used.
Syntax:
ssl_conf_command
name
value
;
ssl_conf_command Options PrioritizeChaCha;
ssl_conf_command Ciphersuites TLS_CHACHA20_POLY1305_SHA256;
These directives are inherited from the previous configuration level
if and only if there are no
ssl_conf_command
directives
defined on the current level.
Note that configuring OpenSSL directly
might result in unexpected behavior.
This directive appeared in version 0.8.7.
Specifies a
file
with revoked certificates (CRL)
in the PEM format used to
verify
client certificates.
Syntax:
ssl_dhparam
file
;
This directive appeared in version 0.7.2.
Specifies a
file
with DH parameters for DHE ciphers.
By default no parameters are set,
and therefore DHE ciphers will not be used.
Prior to version 1.11.0, builtin parameters were used by default.
Requests sent within early data are subject to
replay attacks
.
To protect against such attacks at the application layer,
the
$ssl_early_data
variable
should be used.
proxy_set_header Early-Data $ssl_early_data;
The directive is supported when using OpenSSL 1.1.1 or higher (1.15.4) and
BoringSSL
.
When using OpenSSL 1.0.2 or higher,
it is possible to specify multiple curves (1.11.0), for example:
ssl_ecdh_curve prime256v1:secp384r1;
The special value
auto
(1.11.0) instructs nginx to use
a list built into the OpenSSL library when using OpenSSL 1.0.2 or higher,
or
prime256v1
with older versions.
Prior to version 1.11.0,
the
prime256v1
curve was used by default.
When using OpenSSL 1.0.2 or higher,
this directive sets the list of curves supported by the server.
Thus, in order for ECDSA certificates to work,
it is important to include the curves used in the certificates.
This directive appeared in version 1.19.0.
Enables OCSP validation of the client certificate chain.
The
leaf
parameter
enables validation of the client certificate only.
For the OCSP validation to work,
the
ssl_verify_client
directive should be set to
on
or
optional
.
To resolve the OCSP responder hostname,
the
resolver
directive
should also be specified.
Example:
ssl_verify_client on;
ssl_ocsp on;
resolver 192.0.2.1;
Sets
name
and
size
of the cache
that stores client certificates status for OCSP validation.
The cache is shared between all worker processes.
A cache with the same name can be used in several virtual servers.
The
off
parameter prohibits the use of the cache.
Syntax:
ssl_ocsp_responder
url
;
This directive appeared in version 1.19.0.
Overrides the URL of the OCSP responder specified in the
“
Authority
Information Access
” certificate extension
for
validation
of client certificates.
Only “
http://
” OCSP responders are supported:
ssl_ocsp_responder http://ocsp.example.com/;
Specifies a
file
with passphrases for
secret keys
where each passphrase is specified on a separate line.
Passphrases are tried in turn when loading the key.
Example:
http {
ssl_password_file /etc/keys/global.pass;
server {
server_name www1.example.com;
ssl_certificate_key /etc/keys/first.key;
server {
server_name www2.example.com;
# named pipe can also be used instead of a file
ssl_password_file /etc/keys/fifo;
ssl_certificate_key /etc/keys/second.key;
If the directive is specified
on the
server
level,
the value from the default server can be used.
Details are provided in the
“
Virtual
server selection
” section.
The
TLSv1.1
and
TLSv1.2
parameters
(1.1.13, 1.0.12) work only when OpenSSL 1.0.1 or higher is used.
The
TLSv1.3
parameter (1.13.0) works only when
OpenSSL 1.1.1 or higher is used.
The
TLSv1.3
parameter is used by default
since 1.23.4.
the
server
block will be rejected.
For example, in the following configuration, SSL handshakes with
server names other than
example.com
are rejected:
server {
listen 443 ssl default_server;
ssl_reject_handshake on;
server {
listen 443 ssl;
server_name example.com;
ssl_certificate example.com.crt;
ssl_certificate_key example.com.key;
Sets the types and sizes of caches that store session parameters.
A cache can be of any of the following types:
the use of a session cache is strictly prohibited:
nginx explicitly tells a client that sessions may not be reused.
the use of a session cache is gently disallowed:
nginx tells a client that sessions may be reused, but does not
actually store session parameters in the cache.
builtin
shared
ssl_session_ticket_key
file
;
Sets a
file
with the secret key used to encrypt
and decrypt TLS session tickets.
The directive is necessary if the same key has to be shared between
multiple servers.
By default, a randomly generated key is used.
If several keys are specified, only the first key is
used to encrypt TLS session tickets.
This allows configuring key rotation, for example:
ssl_session_ticket_key current.key;
ssl_session_ticket_key previous.key;
The
file
must contain 80 or 48 bytes
of random data and can be created using the following command:
openssl rand 80 > ticket.key
Depending on the file size either AES256 (for 80-byte keys, 1.11.8)
or AES128 (for 48-byte keys) is used for encryption.
Syntax:
ssl_session_tickets
on
|
off
;
For the OCSP stapling to work, the certificate of the server certificate issuer should be known. If the ssl_certificate file does not contain intermediate certificates, the certificate of the server certificate issuer should be present in the ssl_trusted_certificate file. For a resolution of the OCSP responder hostname, the resolver directive should also be specified. Syntax:
ssl_stapling_file
file
;
This directive appeared in version 1.3.7.
When set, the stapled OCSP response will be taken from the
specified
file
instead of querying
the OCSP responder specified in the server certificate.
The file should be in the DER format as produced by the
“
openssl ocsp
” command.
Syntax:
ssl_stapling_responder
url
;
This directive appeared in version 1.3.7.
Overrides the URL of the OCSP responder specified in the
“
Authority
Information Access
” certificate extension.
Only “
http://
” OCSP responders are supported:
ssl_stapling_responder http://ocsp.example.com/;
This directive appeared in version 1.3.7.
Enables or disables verification of OCSP responses by the server.
For verification to work, the certificate of the server certificate
issuer, the root certificate, and all intermediate certificates
should be configured as trusted using the
ssl_trusted_certificate
directive.
Syntax:
ssl_trusted_certificate
file
;
This directive appeared in version 1.3.7.
Specifies a
file
with trusted CA certificates in the PEM format
used to
verify
client certificates and
OCSP responses if
ssl_stapling
is enabled.
In contrast to the certificate set by
ssl_client_certificate
,
the list of these certificates will not be sent to clients.
Syntax:
ssl_verify_client
on
|
off
|
optional
|
optional_no_ca
;
Enables verification of client certificates.
The verification result is stored in the
$ssl_client_verify
variable.
The
optional
parameter (0.8.7+) requests the client
certificate and verifies it if the certificate is present.
The
optional_no_ca
parameter (1.3.8, 1.2.5)
requests the client
certificate but does not require it to be signed by a trusted CA certificate.
This is intended for the use in cases when a service that is external to nginx
performs the actual certificate verification.
The contents of the certificate is accessible through the
$ssl_client_cert
variable.
Syntax:
ssl_verify_depth
number
;
Error Processing
The
ngx_http_ssl_module
module supports several
non-standard error codes that can be used for redirects using the
error_page
directive:
an error has occurred during the client certificate verification;
a client has not presented the required certificate;
a regular request has been sent to the HTTPS port.
The redirection happens after the request is fully parsed and
the variables, such as
$request_uri
,
$uri
,
$args
and others, are available.
Embedded Variables
The
ngx_http_ssl_module
module supports
embedded variables:
$ssl_alpn_protocol
$ssl_cipher
$ssl_ciphers
$ssl_client_escaped_cert
$ssl_client_cert
$ssl_client_escaped_cert
variable should be used instead.
$ssl_client_fingerprint
$ssl_client_i_dn
$ssl_client_i_dn_legacy
$ssl_client_i_dn
.
$ssl_client_raw_cert
returns the client certificate in the PEM format
for an established SSL connection;
$ssl_client_s_dn
$ssl_client_s_dn_legacy
$ssl_client_s_dn
.
$ssl_client_serial
$ssl_client_v_end
$ssl_client_v_remain
$ssl_client_v_start
$ssl_client_verify
SUCCESS
”, “
FAILED:
reason
”,
and “
NONE
” if a certificate was not present;
Prior to version 1.11.7, the “
FAILED
” result
did not contain the
reason
string.
$ssl_curve
$ssl_curves
$ssl_early_data
1
” if
TLS 1.3
early data
is used
and the handshake is not complete, otherwise “” (1.15.3).
$ssl_protocol
$ssl_server_name
$ssl_session_id
$ssl_session_reused
r
” if an SSL session was reused,
or “
.
” otherwise (1.5.11).