Module ngx_stream_ssl_module
Example of configuration policies ssl_alpn ssl_certificate ssl_certificate_key ssl_ciphers ssl_client_certificate ssl_conf_command ssl_crl ssl_dhparam ssl_ecdh_curve ssl_handshake_timeout ssl_password_file ssl_prefer_server_ciphers ssl_protocols ssl_session_cache ssl_session_ticket_key ssl_session_tickets ssl_session_timeout ssl_trusted_certificate ssl_verify_client ssl_verify_depthEmbedded variables
Module ngx_stream_ssl_module (1.9.0) provides the support necessary for a stream proxy server to work with the SSL/TLS protocol. This module is not built by default, it must be enabled with the -with-stream_ssl_module configuration parameter.
Sample configuration
To reduce processor load, we recommend
- that you set the number of worker processes equal to the number of processors
- cache
- possibly increase the session duration (by default, 5 minutes):
, enable the shared session cache, disable the built-in session
, and
automatic worker_processes; ssl_session_cache shared:SSL:10m; ssl_session_timeout 10m;
Policies
Specifies the list of supported ALPN protocols. One of the protocols must be negotiated if the client uses ALPN:
Specifies a file with the certificate in PEM format for the given server. If intermediate certificates must be specified in addition to a primary certificate, they must 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 can be placed in the same file.
Since version 1.11.0,
this policy can be specified multiple times to upload certificates of different types, for example, RSA and ECDSA: Since version
1.15.9, variables can be used in the file name when using OpenSSL 1.0.2 or higher:
Note that the
Using variables implies that a certificate will be uploaded for each SSL handshake, and this can have a negative impact on performance.
The data:$variable value 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 can have security implications, such as writing secret key data to the error log.
Specifies a file with the secret key
in PEM format for
the specified server. The engine:name:id value can be specified instead of the file
, which loads a secret key with a specified id from the OpenSSL engine name. The data:$variable value can be specified instead of the
file (1.15.10), which loads a secret key of a variable without using intermediate files. Note that inappropriate use of this syntax can have security implications, such as writing secret key data to the error log.
Since version 1.15.9, variables can be used in the file name when using OpenSSL 1.0.2 or higher
.
Specifies the ciphers enabled. Ciphers are specified in the format understood by the OpenSSL library, for example:
The
full list can be viewed using the “openssl ciphers” command.
Specifies a file with trusted CA certificates in the PEM format used to verify client certificates
.
The list of certificates will be sent to clients. If you do not want to, you can use the ssl_trusted_certificate policy.
Set arbitrary OpenSSL configuration commands
.
You can specify multiple
ssl_conf_command policies at the same level:
These policies are
inherited from the previous configuration level if and only if there are no ssl_conf_command policies defined at the current level
.
Specifies a file with revoked certificates (CRLs) in the PEM format used to verify client certificates.
Specifies a file with DH parameters for DHE ciphers.
By default, no parameters are set and therefore DUS ciphers will not be used
.
Specifies a curve for ECDHE ciphers.
When using OpenSSL 1.0.2 or higher, it is possible to specify several curves (1.11.0), for example:
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 earlier versions.
Specifies a timeout for the SSL handshake to complete.
Specifies a passphrase
file for secret keys where each passphrase is specified on a separate line. Passphrases are tested in turn when the key is loaded.
Example:
Specifies that server ciphers should be preferred to client ciphers when using the SSLv3 and TLS
protocols.
Enables the specified protocols
. 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 cannot be reused. Using a session cache is slightly forbidden: Nginx tells a client that sessions can be reused, but doesn’t actually store session parameters in the cache. built on a cache built in OpenSSL; used by a single work process. The cache size is specified in sessions. If the size is not indicated, it is equal to 20480 sessions. Using the built-in cache can cause memory fragmentation. It shared a shared cache among all worker processes. The cache size is specified in bytes; One megabyte can store about 4000 sessions. Each shared cache must have an arbitrary name. A cache with the same name can be used on multiple servers. It is also used to periodically generate, store, and rotate TLS session ticket keys (1.23.2) automatically, unless explicitly configured by the ssl_session_ticket_key policy.
Both types of cache can be used simultaneously, for example:
but using only shared cache without the built-in cache should be more efficient
.
Establishes a file with the secret key used to encrypt and decrypt TLS session tickets. The policy is required if the same key has to be shared between multiple servers. By default, a randomly generated key is used.
If multiple keys are specified, only the first key is used to encrypt TLS session tickets. This allows you to configure key rotation
, for example: The file must contain 80 or 48 bytes of
random data and can be created using the following command:
Depending on the file size, AES256 (for 80-byte keys, 1.11.8) or AES128 (for 48-byte keys) is used for encryption
.
Enables or disables session resumption through TLS session tickets.
Specifies a time during which a client can reuse session parameters.
Specifies a file with trusted CA certificates in the PEM format used to verify
client certificates.
Unlike the certificate set by ssl_client_certificate, the list of these certificates will not be sent to clients
.
Allows verification of client certificates. The result of the verification is stored in the variable $ssl_client_verify. If an error occurred during client certificate verification or if a client did not submit the required certificate, the connection is closed.
The optional parameter requests the client certificate
and checks it if the certificate is present. The
optional_no_ca parameter requests the client certificate, but does not require that it be signed by a trusted CA certificate. This is intended for use in cases where a service that is external to nginx performs the actual verification of the certificate. The contents of the certificate can be accessed through the $ssl_client_cert variable.
Sets the verification depth in the
client certificate chain.
Embedded
variables
The module ngx_stream_ssl_module supports variables since 1.11.2.
$ssl_alpn_protocol returns the protocol selected by ALPN during the SSL handshake, or an empty string (1.21.4); $ssl_cipher returns the name of the encryption used for an established SSL connection; $ssl_ciphers returns the list of ciphers supported by the client (1.11.7). Known ciphers are listed by names, unknown ciphers are displayed in hexadecimal, for example:
$ssl_client_cert returns the client certificate in PEM format for an established SSL connection, with every line except the first prepended with the tab character (1.11.8); $ssl_client_fingerprint returns the SHA1 thumbprint of the client certificate for an established SSL connection (1.11.8); $ssl_client_i_dn returns the “issuer DN” string of the client certificate for an SSL connection established according to RFC 2253 (1.11.8); $ssl_client_raw_cert returns the client certificate in PEM format for an established SSL connection (1.11.8); $ssl_client_s_dn returns the string “subject DN” of the client certificate for an SSL connection established according to RFC 2253 (1.11.8); $ssl_client_serial returns the serial number of the client certificate for an established SSL connection (1.11.8); $ssl_client_v_end returns the end date of the client certificate (1.11.8); $ssl_client_v_remain returns the number of days until the client certificate expires (1.11.8); $ssl_client_v_start returns the start date of the client certificate (1.11.8); $ssl_client_verify returns the result of the client certificate verification (1.11.8): “SUCCESS”, “FAILED:reason“, and “NONE” if there was no certificate; $ssl_curve returns the negotiated curve used for the SSL handshake key exchange process (1.21.5). Known curves are listed by names, unknown curves are displayed in hexadecimal, for example:
$ssl_curves returns the list of curves supported by the client (1.11.7). Known curves are listed by names, unknown curves are displayed in hexadecimal, for example:
$ssl_protocol returns the protocol of an established SSL connection; $ssl_server_name returns the name of the server requested through SNI; $ssl_session_id returns the session ID of an established SSL connection; $ssl_session_reused returns “r” if an SSL session was reused, or “.” otherwise.