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