阅读中文版本

Debug Mutual TLS Handshake Failures

Use openssl s_client to verify the client certificate chain and cipher agreement when mutual TLS handshakes fail intermittently.

openssl s_client -connect api.example.com:443 \
  -cert client.crt -key client.key -CAfile ca.pem -showcerts </dev/null

openssl x509 -in client.crt -noout -dates -subject -issuer

What this recipe does

Diagnose mutual TLS failures by inspecting the presented client chain, roots, and negotiated protocol with openssl.

A service mesh upgrade starts rejecting calls with handshake errors, but only for one workload whose client certificate expired.

Prerequisites

• openssl 3.x
• The client certificate and key
• The server CA bundle

Procedure

1. Run a client-certificate handshake and print the chain.

openssl s_client -connect api.example.com:443 \
  -cert client.crt -key client.key -CAfile ca.pem -showcerts </dev/null

Expected result: The output shows the negotiated protocol and whether the client certificate verifies against the server CA.

2. Inspect certificate validity to catch expiry.

openssl x509 -in client.crt -noout -dates -subject -issuer

Expected result: The notAfter date reveals an expired client certificate when dates are in the past.

How to confirm it worked

Run the commands above and confirm every expected result in order. If a step does not produce the stated output, use the troubleshooting notes before continuing. A passing run shows s_client completes with a verified client chain and the workload succeeds once the certificate is renewed.

Troubleshooting

Server requests a client cert but none is sent — Confirm the client is configured to present a certificate; some clients only send it after a challenge.

Cipher mismatch — Compare the server advertised cipher list with the client; align on a mutually supported suite.

Limitations

• openssl reproduces the handshake but not application-layer authorization.
• Does not cover rotating certificates automatically.
• Requires handling private keys securely.