The SSL module enables HTTPS support, HTTP over SSL/TLS in particular. It gives you the possibility to serve secure websites by providing a certificate, a certificate key, and other parameters, defined with the following directives:
Directive |
Description |
ssl Context: http, server |
Enables HTTPS for the specified server. This directive is the equivalent of listen 443 ssl, or listen port ssl, more generally. Syntax: on or off Default: ssl off; |
ssl_certificate Context: http, server |
Sets the path of the PEM certificate. This directive can be specified multiple times to load certificates of different types. Syntax: File path |
ssl_certificate_key Context: http, server |
Sets the path of the PEM secret key file. This directive can be specified multiple times to load certificates of different types. Syntax: File path |
ssl_client_certificate Context: http, server |
Sets the path of the client PEM certificate. Syntax: File path |
ssl_crl Context: http, server |
Orders Nginx to load a CRL (Certificate Revocation List) file, which allows checking the revocation status of certificates. |
ssl_dhparam Context: http, server |
Sets the path of the Diffie-Hellman parameters file. Syntax: File path. |
ssl_protocols Context: http, server |
Specifies the protocol that should be employed. Syntax: ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3]; Default: ssl_protocols TLSv1 TLSv1.1 TLSv1.2 TLSv1.3; |
ssl_ciphers Context: http, server |
Specifies the ciphers that should be employed. The list of available ciphers can be obtained by running the following command from the shell: openssl ciphers. Syntax: ssl_ciphers cipher1[:cipher2...]; Default: ssl_ciphers ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP; |
ssl_prefer_server_ciphers Context: http, server |
Specifies whether server ciphers should be preferred over client ciphers. Syntax: on or off Default: off |
ssl_verify_client Context: http, server |
Enables verifying certificates transmitted by the client and sets the result in the $ssl_client_verify. The optional_no_ca value verifies the certificate if there is one, but does not require it to be signed by a trusted CA certificate. Syntax: on | off | optional | optional_no_ca Default: off |
ssl_verify_depth Context: http, server |
Specifies the verification depth of the client certificate chain. Syntax: Numeric value Default: 1 |
ssl_session_cache Context: http, server |
Configures the cache for SSL sessions. Syntax: off, none, builtin:size or shared:name:size Default: off (disables SSL sessions) |
ssl_session_timeout Context: http, server |
When SSL sessions are enabled, this directive defines the timeout for using session data. Syntax: Time value Default: 5 minutes |
ssl_password_phrase Context: http, server |
Specifies a file containing passphrases for secret keys. Each passphrase is specified on a separate line; they are tried one after the other when loading a certificate key. Syntax: Filename Default: (none) |
ssl_buffer_size Context: http, server |
Specifies buffer size when serving requests over SSL. Syntax: Size value Default: 16k |
ssl_session_tickets Context: http, server |
Enables TLS session tickets, allowing for the client to reconnect faster, skipping renegotiation. Syntax: on or off Default: on |
ssl_session_ticket_key Context: http, server |
Sets the path of the key file used to encrypt and decrypt TLS session tickets. By default, a random value is generated. Syntax: file name Default: (none) |
ssl_trusted_certificate Context: http, server |
Sets the path of a trusted certificate file (PEM format), used to validate authenticity of client certificates, as well as stapling of OCSP responses. More about SSL stapling can be found here: Syntax: Filename Default: (none) |
Additionally, the following variables are made available:
- $ssl_cipher: Indicates the cipher used for the current request
- $ssl_ciphers: Returns list of client supported ciphers
- $ssl_curves: Returns list of client supported curves
- $ssl_client_serial: Indicates the serial number of the client certificate
- $ssl_client_s_dn and $ssl_client_i_dn: Indicates the value of the subject and issuer DN of the client certificate
- $ssl_protocol: Indicates the protocol at use for the current request
- $ssl_client_cert and $ssl_client_raw_cert: Returns client certificate data, which is raw data for the second variable
- $ssl_client_verify: Set to SUCCESS if the client certificate was successfully verified
- $ssl_session_id: Allows you to retrieve the ID of an SSL session
- $ssl_client_escaped_cert: Returns the client certificate in PEM format