ngx_http_ssl_module

HTTPS support with certificates, protocols, ciphers and sessions

compiled inBSD-2-Clausesource docs

Overview

ngx_http_ssl_module provides the support needed for HTTPS. A server block becomes a TLS server through the ssl parameter of the listen directive, and the module loads the PEM certificate and key, selects the enabled protocols and ciphers, and manages session caching and resumption.

Since 1.11.0 ssl_certificate can be given more than once to serve RSA and ECDSA certificates side by side, and since 1.15.9 the file name may contain variables. The module adds the 495, 496 and 497 error codes for error_page and exposes variables such as $ssl_protocol, $ssl_cipher, $ssl_server_name, $ssl_session_reused, $ssl_early_data and the $ssl_client_* family for client certificates.

It is an official nginx module that requires the OpenSSL library and is not built by default upstream, so it needs the --with-http_ssl_module configure parameter. The typical use is terminating TLS for every public site and API served by nginx.

Key directives

ssl_certificatePEM file with the certificate and any intermediates; may be repeated for RSA and ECDSA certificates since 1.11.0.
ssl_certificate_keyPEM file with the secret key; engine:, store: and data:$variable forms are also accepted.
ssl_protocolsEnables the listed protocol versions, default TLSv1.2 TLSv1.3 (TLSv1.3 by default since 1.23.4).
ssl_ciphersCipher list in OpenSSL format, default HIGH:!aNULL:!MD5.
ssl_session_cacheSession parameter cache; default none, shared:name:size is recommended and holds about 4000 sessions per megabyte.
ssl_staplingEnables stapling of OCSP responses by the server, default off; needs a resolver and the issuer certificate.

Example

nginx.conf
server { listen 443 ssl; server_name example.com; ssl_certificate /etc/nginx/ssl/example.com.crt; ssl_certificate_key /etc/nginx/ssl/example.com.key; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers HIGH:!aNULL:!MD5; # shared cache across workers, 1m holds about 4000 sessions ssl_session_cache shared:SSL:10m; ssl_session_timeout 10m; ssl_stapling on; ssl_stapling_verify on; resolver 192.0.2.1; }

Availability

Compiled into every n.wtf nginx binary. Install nginx-extras and the directives above work out of the box, no load_module line needed.