DEV Community

Deep Fix
Deep Fix

Posted on

How to Resolve SSL/TLS Certificate Handshake Failures – Debugging TLS Errors for DevOps

#ssl #tls #debug #devops

How to Resolve SSL/TLS Certificate Handshake Failures

Audience: Software developers, engineers, and DevOps professionals.

Why Handshake Failures Occur

Handshake failures happen when the client and server cannot agree on a mutually trusted certificate chain, supported protocol version, or cipher suite. Common root causes include:

  • Expired or revoked certificates
  • Missing intermediate certificates
  • TLS version mismatch (e.g., server only supports TLS 1.2 while client forces TLS 1.3)
  • Weak or disabled cipher suites
  • Incorrect hostname verification

Step‑by‑Step Troubleshooting

1. Verify the Server Certificate Chain 

openssl s_client -connect myservice.example.com:443 -servername myservice.example.com
Enter fullscreen mode Exit fullscreen mode

Check the output for Verify return code: 0 (ok). If you see unable to get local issuer certificate, the server is missing an intermediate.

2. Check TLS Version Compatibility 

curl -v --tlsv1.2 https://myservice.example.com
Enter fullscreen mode Exit fullscreen mode

If the connection succeeds with --tlsv1.2 but fails with the default, the server may have disabled older versions. Adjust your client’s SSLContext accordingly.

3. Inspect the Client Trust Store 

import ssl, socket
context = ssl.create_default_context()
conn = context.wrap_socket(socket.socket(socket.AF_INET), server_hostname="myservice.example.com")
conn.connect(("myservice.example.com", 443))
Enter fullscreen mode Exit fullscreen mode

Running this script will raise an ssl.SSLCertVerificationError if the CA bundle is outdated. Update the bundle (apt-get install ca-certificates or update-ca-trust).

4. Resolve Common Issues

  • Expired certificate – Renew the cert and reload the service.
  • Hostname mismatch – Ensure the CN or SAN includes the exact hostname used by the client.
  • Missing intermediate – Concatenate the leaf and intermediate certs into a single file (cat cert.pem intermediate.pem > fullchain.pem).
  • Weak ciphers – Enable modern cipher suites in your server config (e.g., ssl_ciphers 'HIGH:!aNULL:!MD5'; for Nginx).

Automated Fix Script

You can automate many of these checks with a ready‑made script. Download the pre‑configured script here. Alternatively, Get the complete patch tool or Access the full repository fix.

Summary

  1. Validate the full certificate chain with openssl.
  2. Confirm TLS version support on both sides.
  3. Update the client trust store to include the latest CA roots.
  4. Fix configuration errors (hostname, cipher suites, expirations).

By following these steps, developers and DevOps engineers can quickly identify and resolve SSL/TLS handshake failures, keeping services secure and reliable.

Top comments (0)