Configure nginx TLS protocols and ciphers

The fix/etc/nginx/nginx.conf

ssl_protocols TLSv1.2 TLSv1.3;
ssl_prefer_server_ciphers off;
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 1d;
ssl_session_tickets off;

sudo nginx -t && sudo systemctl reload nginx

Directives on this page

ssl_protocols

The TLS versions the server will negotiate. This became the default in two steps — TLSv1.3 was enabled in 1.23.4 and TLSv1 and TLSv1.1 were disabled in 1.27.3 — so on 1.27.3 or newer the line is a verify, and on anything older it is a real change.

• acceptsSSLv2 | SSLv3 | TLSv1 | TLSv1.1 | TLSv1.2 | TLSv1.3
• defaultssl_protocols TLSv1.2 TLSv1.3;
• valid inhttp, server

nginx.org ngx_http_ssl_module docs; version history from nginx.org CHANGES

ssl_prefer_server_ciphers

Whether the server's cipher order wins over the client's. Mozilla's intermediate profile now recommends leaving it off, which is also the default.

• acceptson | off
• defaultssl_prefer_server_ciphers off;
• valid inhttp, server

nginx.org ngx_http_ssl_module docs

ssl_session_tickets

Session resumption via tickets. On by default; turning it off removes the ticket key as a forward-secrecy liability.

• acceptson | off
• defaultssl_session_tickets on;
• valid inhttp, server

nginx.org ngx_http_ssl_module docs

If you see this

nginx: [emerg] invalid value "TLSv1_2" in /etc/nginx/nginx.conf:8

ssl_protocols matches each token literally against a fixed list. The separator is a dot, not an underscore, and the list stops at TLSv1.3 — so a typo and a version that does not exist fail identically. — nginx/src/core/ngx_conf_file.c

nginx: [emerg] "ssl_protocols" must enable TLSv1.3 for the "listen ... quic" directive in /etc/nginx/nginx.conf:7

HTTP/3 is TLS 1.3 only. A protocol line hardened for HTTP/2 keeps working until a quic listener is added, and then refuses to start — the config did not change, the listener did. — nginx/src/http/modules/ngx_http_ssl_module.c

Check your version first — that first line may already be the default

ssl_protocols TLSv1.2 TLSv1.3; is now nginx’s own default, so on a current build the first line of the block above changes nothing. It is worth writing anyway — an explicit protocol line survives a distro that patches defaults, and it documents intent — but you should know which of these you are doing.

nginx moved to that default in two steps, and its own changelog dates both:

Release	Change
1.23.4 (28 Mar 2023)	TLSv1.3 enabled by default
1.27.3 (26 Nov 2024)	TLSv1 and TLSv1.1 disabled by default

So:

• nginx 1.27.3 or newer — the default is already TLSv1.2 TLSv1.3. Setting it is a verify, not a fix.
• anything older — TLS 1.0 and 1.1 are still enabled by default and the line is a real change.

That second case is not hypothetical. nginx’s legacy branches are 1.28.x and 1.26.x, and distribution packages sit further back still, so a long-term server is exactly where the line does work. Check before assuming:

nginx -v

The rest of the block is not a no-op on any version. ssl_session_tickets off; differs from the default, and the two ssl_ciphers facts below — that it does not control TLS 1.3, and that a hand-written list ages badly — are the parts of this page that actually change outcomes.

Why it matters

TLS 1.0 and 1.1 are obsolete, deprecated by the IETF, and rejected by current browsers. Leaving them enabled doesn’t help anyone reach your site — the clients that would need them can’t complete a modern handshake anyway — but it does keep you failing compliance scans and offering downgrade surface.

ssl_protocols TLSv1.2 TLSv1.3 is the whole control. The rest of this page is about not making things worse.

Don’t hand-write ssl_ciphers

The same argument as SSH ciphers applies, for the same reason: cipher lists age badly, and a list pasted from a 2016 blog post encodes 2016’s opinions forever.

Use the Mozilla SSL Configuration Generator. It produces a current list for your nginx and OpenSSL versions, and it is maintained by people who track this full time. Pick the intermediate profile unless you have a specific reason — modern drops TLS 1.2 entirely, which is more compatibility loss than most sites can absorb.

If you inherit a config with a long ssl_ciphers line, the question isn’t whether the ciphers are bad — they’re probably fine. It’s whether anyone will revisit them when the next weakness lands. A generated config that you regenerate is more durable than a curated one that you won’t.

ssl_ciphers does not control TLS 1.3

This surprises people who carefully craft a cipher list and then wonder why their scan still shows suites they didn’t list.

ssl_ciphers configures TLS 1.2 and below only. TLS 1.3 has its own separate cipher suite set, and nginx offers no directive for it — OpenSSL’s defaults apply and they are deliberately short and all strong. There is nothing to tune, and nothing you can break.

So a hand-written ssl_ciphers line governs a shrinking share of your traffic, which is another reason not to spend effort on it.

ssl_prefer_server_ciphers off is deliberate

The old advice was on — let the server dictate the order. Current Mozilla guidance for the intermediate profile is off, because modern clients pick better than a fixed server-side ordering can. A phone with hardware AES and a laptop without it want different suites, and only the client knows which it is.

ssl_session_tickets off is the other non-obvious one: tickets can undermine forward secrecy unless the ticket key is rotated, and nginx has no built-in rotation.

Verify it worked

Check the effective config, not one file:

sudo nginx -T 2>/dev/null | grep -E 'ssl_protocols|ssl_ciphers|ssl_prefer_server_ciphers'

Then test what the server actually negotiates — TLS 1.0 must fail:

openssl s_client -connect your.site:443 -tls1 </dev/null 2>&1 | grep -E 'Protocol|alert|handshake failure'

Expect a handshake failure. And confirm 1.3 works:

openssl s_client -connect your.site:443 -tls1_3 </dev/null 2>&1 | grep -E 'Protocol|Cipher'

For a full external picture, run the site through the SSL Labs server test — it enumerates every suite and protocol from the outside, which is the view an attacker and a compliance scanner both have.

Before you apply this

Dropping TLS 1.0/1.1 breaks genuinely old clients, and the failure looks like your site being down rather than a protocol negotiation problem.

Realistically affected: Android 4.x, IE on Windows 7 without the registry opt-in, Java 7, OpenSSL 0.9.8 era tooling, and — most commonly in practice — payment terminals, embedded devices, and an internal script running on a server nobody has upgraded.

Look before you cut. If you log the protocol, you can count what you’re about to break:

log_format ssl_info '$remote_addr $ssl_protocol $ssl_cipher "$http_user_agent"';
access_log /var/log/nginx/ssl.log ssl_info;

Leave that for a week and check:

awk '{print $2}' /var/log/nginx/ssl.log | sort | uniq -c | sort -rn

If TLSv1 and TLSv1.1 are zero — which they will be on most public sites — this change is free. If they aren’t, you now know exactly who to talk to instead of finding out from a support ticket.

Reload rather than restart, and nginx -t first.

Related

• Enable HSTS — TLS is only useful if the browser insists on it.
• OCSP stapling — mostly moot now; read before enabling.