Ssl_Verify_Depth
Module ngx_http_ssl_module – Nginx.org
The ngx__ssl_module module provides the
necessary support for HTTPS.
This module is not built by default, it should be enabled with the
–with-_ssl_module
configuration parameter.
This module requires the
OpenSSL library.
Example Configuration
To reduce the processor load it is recommended to
set the number of
worker processes
equal to the number of processors,
enable
keep-alive
connections,
enable the shared session cache,
disable the built-in session cache,
and possibly increase the session lifetime
(by default, 5 minutes):
worker_processes auto;
{…
server {
listen 443 ssl;
keepalive_timeout 70;
ssl_protocols TLSv1 TLSv1. 1 TLSv1. 2;
ssl_ciphers AES128-SHA:AES256-SHA:RC4-SHA:DES-CBC3-SHA:RC4-MD5;
ssl_certificate /usr/local/nginx/conf/;
ssl_certificate_key /usr/local/nginx/conf/;
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 10m;… }
Directives
Syntax:
ssl on | off;
Default:
ssl off;
Context:, server
This directive was made obsolete in version 1. 15. 0.
The ssl parameter
of the listen directive
should be used instead.
ssl_buffer_size size;
ssl_buffer_size 16k;
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;
ssl_certificate file;
—
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_name;
ssl_certificate;
ssl_certificate_key;
ssl_certificate_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. 9, variables can be used in the file name
when using OpenSSL 1. 2 or higher:
ssl_certificate $;
ssl_certificate_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. 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.
ssl_certificate_key file;
Specifies a file with the secret key in the PEM format
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.
which loads a secret key from a variable without using intermediate files.
when using OpenSSL 1. 2 or higher.
ssl_ciphers ciphers;
ssl_ciphers HIGH:! aNULL:! MD5;
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
ciphers by default.
ssl_client_certificate file;
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.
ssl_conf_command command;
This directive appeared in version 1. 19. 4.
Sets arbitrary OpenSSL configuration
commands.
The directive is supported when using OpenSSL 1. 2 or higher.
Several ssl_conf_command directives
can be specified on the same level:
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.
ssl_crl file;
This directive appeared in version 0. 8. 7.
Specifies a file with revoked certificates (CRL)
in the PEM format used to verify
client certificates.
ssl_dhparam file;
This directive appeared in version 0. 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. 0, builtin parameters were used by default.
ssl_early_data on | off;
ssl_early_data off;
This directive appeared in version 1. 3.
Enables or disables TLS 1. 3
early data.
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. 4) and
BoringSSL.
ssl_ecdh_curve curve;
ssl_ecdh_curve auto;
This directive appeared in versions 1. 0 and 1. 6.
Specifies a curve for ECDHE ciphers.
When using OpenSSL 1. 2 or higher,
it is possible to specify multiple curves (1. 0), for example:
ssl_ecdh_curve prime256v1:secp384r1;
The special value auto (1. 0) instructs nginx to use
a list built into the OpenSSL library when using OpenSSL 1. 2 or higher,
or prime256v1 with older versions.
Prior to version 1. 0,
the prime256v1 curve was used by default.
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.
ssl_ocsp on |
off |
leaf;
ssl_ocsp off;
This directive appeared in version 1. 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. 2. 1;
ssl_ocsp_cache
[shared:name:size];
ssl_ocsp_cache off;
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.
ssl_ocsp_responder url;
Overrides the URL of the OCSP responder specified in the
“Authority
Information Access” certificate extension
for validation of client certificates.
Only “” OCSP responders are supported:
ssl_ocsp_responder
ssl_password_file file;
This directive appeared in version 1. 3.
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.
{
ssl_password_file /etc/keys/;…
ssl_certificate_key /etc/keys/;}
# named pipe can also be used instead of a file
ssl_password_file /etc/keys/fifo;
ssl_certificate_key /etc/keys/;}}
ssl_prefer_server_ciphers on | off;
ssl_prefer_server_ciphers off;
Specifies that server ciphers should be preferred over client
ciphers when using the SSLv3 and TLS protocols.
ssl_protocols
[SSLv2]
[SSLv3]
[TLSv1]
[TLSv1. 1]
[TLSv1. 2]
[TLSv1. 3];
Enables the specified protocols.
The TLSv1. 1 and TLSv1. 2 parameters
(1. 13, 1. 12) work only when OpenSSL 1. 1 or higher is used.
The TLSv1. 3 parameter (1. 13. 0) works only when
OpenSSL 1. 1 or higher is used.
ssl_reject_handshake on | off;
ssl_reject_handshake off;
If enabled, SSL handshakes in
the server block will be rejected.
For example, in the following configuration, SSL handshakes with
server names other than are rejected:
listen 443 ssl default_server;
ssl_reject_handshake on;}
ssl_certificate_key;}
ssl_session_cache
none |
[builtin[:size]]
ssl_session_cache none;
Sets the types and sizes of caches that store session parameters.
A cache can be of any of the following types:
off
the use of a session cache is strictly prohibited:
nginx explicitly tells a client that sessions may not be reused.
none
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
a cache built in OpenSSL; used by one worker process only.
The cache size is specified in sessions.
If size is not given, it is equal to 20480 sessions.
Use of the built-in cache can cause memory fragmentation.
shared
a cache shared between all worker processes.
The cache size is specified in bytes; one megabyte can store
about 4000 sessions.
Each shared cache should have an arbitrary name.
Both cache types can be used simultaneously, for example:
ssl_session_cache builtin:1000 shared:SSL:10m;
but using only shared cache without the built-in cache should
be more efficient.
ssl_session_ticket_key file;
This directive appeared in version 1. 7.
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;
The file must contain 80 or 48 bytes
of random data and can be created using the following command:
openssl rand 80 >
Depending on the file size either AES256 (for 80-byte keys, 1. 8)
or AES128 (for 48-byte keys) is used for encryption.
ssl_session_tickets on | off;
ssl_session_tickets on;
Enables or disables session resumption through
TLS session tickets.
ssl_session_timeout time;
ssl_session_timeout 5m;
Specifies a time during which a client may reuse the
session parameters.
ssl_stapling on | off;
ssl_stapling off;
This directive appeared in version 1. 3. 7.
Enables or disables
stapling
of OCSP responses by the server.
ssl_stapling on;
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,
ssl_stapling_file file;
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.
ssl_stapling_responder url;
Information Access” certificate extension.
ssl_stapling_responder
ssl_stapling_verify on | off;
ssl_stapling_verify off;
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.
ssl_trusted_certificate file;
In contrast to the certificate set by ssl_client_certificate,
the list of these certificates will not be sent to clients.
ssl_verify_client
on | off |
optional | optional_no_ca;
ssl_verify_client off;
Enables verification of client certificates.
The verification result is stored in the
$ssl_client_verify variable.
The optional parameter (0. 7+) requests the client
certificate and verifies it if the certificate is present.
The optional_no_ca parameter (1. 8, 1. 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.
ssl_verify_depth number;
ssl_verify_depth 1;
Sets the verification depth in the client certificates chain.
Error Processing
The ngx__ssl_module module supports several
non-standard error codes that can be used for redirects using the
error_page directive:
495
an error has occurred during the client certificate verification;
496
a client has not presented the required certificate;
497
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__ssl_module module supports
embedded variables:
$ssl_cipher
returns the name of the cipher used
for an established SSL connection;
$ssl_ciphers
returns the list of ciphers supported by the client (1. 7).
Known ciphers are listed by names, unknown are shown in hexadecimal,
AES128-SHA:AES256-SHA:0x00ff
The variable is fully supported only when using OpenSSL version 1. 2 or higher.
With older versions, the variable is available
only for new sessions and lists only known ciphers.
$ssl_client_escaped_cert
returns the client certificate in the PEM format (urlencoded)
for an established SSL connection (1. 5);
$ssl_client_cert
returns the client certificate in the PEM format
for an established SSL connection, with each line except the first
prepended with the tab character;
this is intended for the use in the
proxy_set_header directive;
The variable is deprecated,
the $ssl_client_escaped_cert variable should be used instead.
$ssl_client_fingerprint
returns the SHA1 fingerprint of the client certificate
for an established SSL connection (1. 1);
$ssl_client_i_dn
returns the “issuer DN” string of the client certificate
for an established SSL connection according to
RFC 2253 (1. 6);
$ssl_client_i_dn_legacy
Prior to version 1. 6, the variable name was $ssl_client_i_dn.
$ssl_client_raw_cert
$ssl_client_s_dn
returns the “subject DN” string of the client certificate
$ssl_client_s_dn_legacy
Prior to version 1. 6, the variable name was $ssl_client_s_dn.
$ssl_client_serial
returns the serial number of the client certificate
$ssl_client_v_end
returns the end date of the client certificate (1. 7);
$ssl_client_v_remain
returns the number of days
until the client certificate expires (1. 7);
$ssl_client_v_start
returns the start date of the client certificate (1. 7);
$ssl_client_verify
returns the result of client certificate verification:
“SUCCESS”, “FAILED:reason”,
and “NONE” if a certificate was not present;
Prior to version 1. 7, the “FAILED” result
did not contain the reason string.
$ssl_curves
returns the list of curves supported by the client (1. 7).
Known curves are listed by names, unknown are shown in hexadecimal,
0x001d:prime256v1:secp521r1:secp384r1
The variable is supported only when using OpenSSL version 1. 2 or higher.
With older versions, the variable value will be an empty string.
The variable is available only for new sessions.
$ssl_early_data
returns “1” if
TLS 1. 3 early data is used
and the handshake is not complete, otherwise “” (1. 3).
$ssl_protocol
returns the protocol of an established SSL connection;
$ssl_server_name
returns the server name requested through
SNI
(1. 0);
$ssl_session_id
returns the session identifier of an established SSL connection;
$ssl_session_reused
returns “r” if an SSL session was reused,
or “. ” otherwise (1. 11).
NGinx SSL certificate authentication signed … – Stack Overflow
Edit: I had also this “problem”, solution and explanation is at the bottom of the text.
It seemed like nginx doesn’t support intermediate certificates. My certs self created: (RootCA is selfsigned, IntrermediateCA1 is signed by RootCA, etc. )
RootCA -> IntermediateCA1 -> Client1
RootCA -> IntermediateCA2 -> Client2
I want to use in nginx “IntermediateCA1”, to allow access to site only to owner of the “Client1” certificate.
When I put to “ssl_client_certificate” file with IntermediateCA1 and RootCA, and set “ssl_verify_depth 2” (or more), clients can login to site both using certificate Client1 and Client2 (should only Client1).
The same result is when I put to “ssl_client_certificate” file with only RootCA – both clients can login.
When I put to “ssl_client_certificate” file with only IntermediateCA1, and set “ssl_verify_depth 1” (or “2” or more – no matter), it is imposible to log in, I get error 400. And in debug mode i see logs:
verify:0, error:20, depth:1, subject:”/C=PL/CN=IntermediateCA1/”, issuer: “/C=PL/CN=RootCA/”
verify:0, error:27, depth:1, subject:”/C=PL/CN=IntermediateCA1/”, issuer: “/C=PL/CN=RootCA/”
verify:1, error:27, depth:0, subject:”/C=PL/CN=Client1/”, issuer: “/C=PL/CN=IntermediateCA1/”
(.. )
client SSL certificate verify error: (27:certificate not trusted) while reading client request headers, (.. )
I thing this is a bug. Tested on Ubuntu, nginx 1. 1. 19 and 1. 2. 7-1~dotdeb. 1, openssl 1. 0. 1.
I see that nginx 1. 3 has few more options about using client certificates, but I’dont see solution to this problem.
Currently, the only one way to separate clients 1 and 2 is to create two, selfsigned RootCAs, but this is only workaround..
Edit 1:
I’ve reported this issue here:
Edit 2″
*Ok, it’s not a bug, it is feature;)*
I get response here: It is working, you must only check what your ssl_client_i_dn is (. Instead of issuer you can use also subject of certificate, or what you want from
This is how certificate verification works: certificate must be
verified up to a trusted root. If chain can’t be built to a trusted
root (not intermediate) – verification fails. If you trust root – all
certificates signed by it, directly or indirectly, will be
successfully verified.
Limiting verification depth may be used if you
want to limit client certificates to a directly issued certificates
only, but it’s more about DoS prevention, and obviously it can’t be
used to limit verificate to intermediate1 only (but not
intermediate2).
What you want here is some authorization layer based
on the verification result – i. e. you may want to check that client’s
certificate issuer is intermediate1. Simplest solution would be to
reject requests if issuer’s DN doesn’t match one allowed, e. g.
something like this (completely untested):
[ Edit by me, it is working correctly in my configuration]
server {
listen 443 ssl;
ssl_certificate…
ssl_certificate_key…
ssl_client_certificate /path/to/;
ssl_verify_client on;
ssl_verify_depth 2;
if ($ssl_client_i_dn! = “/C=PL/CN=IntermediateCA1/”) {
return 403;}}
SSLVerifyDepth explaination – Server Fault
As per my tests (see this comment) and this answer, the certificate chain verification in apache works like this:
current_certificate:= client_certificate_from_request
current_depth:= 0
LOOP
if current_certificate IS self-signed (ie. root)
if current_certificate IS IN SSLCACertificateFile
THEN RETURN true // cert is accepted as valid
ELSE RETURN false // validation failed
end if
current_certificate:= tIssuer()
current_depth += 1
if current_depth > SSLVerifyDepth
THEN RETURN false // validation failed
END LOOP // repeat
In words:
The final root certificate must be in the SSLCACertificateFile (or alternatively in SSLCACertificatePath) otherwise the client certificate is not accepted valid. The SSLVerifyDepth parameter limits how far the chain will apache look. If the limit is reached, the certificate is rejected.
The intermediate certificates listed in SSLCACertificateFile only affect building the chain (for example when the client does not send the full chain, so without those listed on the SSLCACertificateFile apache d would not have a way to reach the root certificate), but the validity depends only on the presence of the root certificate in SSLCACertificateFile.
Frequently Asked Questions about ssl_verify_depth
What is Ssl_verify_depth?
ssl_verify_depth -> sets a verification depth in the client certificates chain. Authority provides a bundle of chained certificates which should be concatenated to the signed server certificate.Jun 23, 2012
What is Ssl_password_file?
Nginx has ssl_password_file parameter. 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.Oct 13, 2015
What is Ssl_session_cache?
a cache built in OpenSSL; used by one worker process only. The cache size is specified in sessions. If size is not given, it is equal to 20480 sessions. … ssl_session_cache builtin:1000 shared:SSL:10m; but using only shared cache without the built-in cache should be more efficient.
