DEV Community

Deep Fix
Deep Fix

Posted on

How to Fix SSL/TLS Certificate Handshake Failures – A Complete DevOps Guide

#ssl #tls #devops #troubleshooting

Introduction

SSL/TLS handshake failures are a common pain point for developers and DevOps engineers. This guide walks you through the most frequent causes and provides step‑by‑step troubleshooting commands you can run right now.

1. Verify System Clock

An out‑of‑sync clock is the simplest reason for a handshake error. On Linux you can check and sync time with:

date
sudo timedatectl status
sudo timedatectl set-ntp true
Enter fullscreen mode Exit fullscreen mode

2. Inspect the Certificate Chain

Use openssl to see what the server actually presents:

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

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

3. Update Your Trust Store

Linux (Debian/Ubuntu) 

sudo apt-get update && sudo apt-get install -y ca-certificates
sudo update-ca-certificates
Enter fullscreen mode Exit fullscreen mode

Red Hat / CentOS 

sudo yum reinstall ca-certificates
sudo update-ca-trust force-enable
Enter fullscreen mode Exit fullscreen mode

Java Runtime

If your Java app still fails, import the missing cert into the JDK truststore:

keytool -importcert -file server.crt -keystore $JAVA_HOME/lib/security/cacerts -alias myserver -storepass changeit
Enter fullscreen mode Exit fullscreen mode

4. Enforce Compatible Protocols

Older clients may try TLS 1.0/1.1, which many servers have disabled. Force TLS 1.2 or higher:

export CURL_SSLVERSION=TLSv1.2
curl --tlsv1.2 https://example.com
Enter fullscreen mode Exit fullscreen mode

Or in Python:

import ssl, socket
ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
ctx.minimum_version = ssl.TLSVersion.TLSv1_2
with ctx.wrap_socket(socket.socket(), server_hostname="example.com") as s:
    s.connect(("example.com", 443))
    print(s.version())
Enter fullscreen mode Exit fullscreen mode

5. Debug with Wireshark or tcpdump

Capture the handshake to see where it aborts:

sudo tcpdump -i any -w handshake.pcap port 443
Enter fullscreen mode Exit fullscreen mode

Open the .pcap file in Wireshark and filter for tls packets.

6. Apply a Ready‑Made Fix

If you prefer an automated approach, we’ve prepared a pre‑built script that updates the trust store, forces TLS 1.2, and reloads affected services.

Conclusion

By validating time, inspecting the certificate chain, keeping your trust store current, and ensuring protocol compatibility, you can eliminate the majority of SSL/TLS handshake failures. Keep this checklist handy and automate the repetitive steps with the script above to reduce downtime.

Top comments (0)