kb/tls_handshake.md

TLS Handshake Issues

Symptoms

• SSLHandshakeException, certificate verify failed, or unknown_ca
• Works with curl -k but fails with client defaults
• Errors after certificate rotation

Checks

• Validate certificate chain, expiry, and SAN/hostname match
• Confirm protocol/cipher compatibility between client and server
• Check ALPN/SNI configuration for proxies or ingress
• Inspect system trust store and custom CA bundles
• Review mTLS settings and key/cert presence

Fix

• Install correct CA bundle and full certificate chain
• Align TLS versions/ciphers or disable legacy protocols
• Configure SNI/ALPN correctly on clients and proxies
• Rotate certificates/keys and restart workloads