TLS · 4 steps

TLS handshake is failing

Get the server to tell you what it is presenting, then work through name, chain, expiry, protocol and client certificates in the order they fail.

Every step

Ask the server what it presents

Client error messages are summaries. s_client shows the actual chain, the negotiated protocol and the verify result, which usually names the problem outright.

$ openssl s_client -connect <host>:443 -servername <host> </dev/null

$ openssl s_client -connect <host>:443 -servername <host> </dev/null 2>/dev/null | openssl x509 -noout -subject -issuer -dates -ext subjectAltName

Look for: The `Verify return code:` line at the bottom, the certificate chain above it, and the negotiated protocol and cipher.

Check the chain the server sends

The most common TLS misconfiguration is a server sending only its leaf certificate. Browsers often paper over it by fetching the intermediate; curl, Java and Go usually do not, which is why "it works in my browser" and the API call fails.

$ openssl s_client -connect <host>:443 -servername <host> -showcerts </dev/null

$ openssl s_client -connect <host>:443 -servername <host> </dev/null 2>&1 | grep -A3 "Certificate chain"

$ openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt -untrusted chain.pem cert.pem

Look for: How many certificates come back. A leaf plus at least one intermediate is normal; a lone leaf for a publicly-issued certificate is the bug.

Check protocol and cipher agreement

A handshake that fails before any certificate appears is usually the two sides failing to agree on a protocol version or cipher — increasingly common as TLS 1.0 and 1.1 get switched off.

$ openssl s_client -connect <host>:443 -tls1_2 </dev/null 2>&1 | head -5

$ openssl s_client -connect <host>:443 -tls1_3 </dev/null 2>&1 | head -5

$ nmap --script ssl-enum-ciphers -p 443 <host>

Look for: Which versions complete a handshake. "no protocols available" or "wrong version number" names the problem directly.

Work through the mutual TLS handshake

mTLS adds a second certificate in the other direction, and the failure messages are notoriously unhelpful. Nearly all of it comes down to three things: the right extended key usage, a chain the server trusts, and the client actually sending it.

$ openssl s_client -connect <host>:443 -cert client.crt -key client.key -CAfile ca.crt </dev/null

$ openssl x509 -in client.crt -noout -ext extendedKeyUsage

$ openssl verify -CAfile ca.crt client.crt

$ openssl s_client -connect <host>:443 </dev/null 2>&1 | grep -i "acceptable client certificate"

Look for: Whether the EKU includes clientAuth, whether verify passes against the CA the server trusts, and which CA names the server says it will accept.