DEV Community

Deep Fix
Deep Fix

Posted on

SSL/TLS Certificate Handshake Failure Resolution Guide – Tips for Developers & DevOps

#ssl #tls #devops #troubleshooting

SSL/TLS Certificate Handshake Failure Resolution Guide

When a client and server can't agree on a certificate during the TLS handshake, you’ll see errors like SSL handshake failed, CERTIFICATE_VERIFY_FAILED, or ERR_SSL_PROTOCOL_ERROR. This article walks you through the most common causes and provides step‑by‑step remediation for developers, engineers, and DevOps teams.

Common Symptoms

  • curl: (60) SSL: certificate subject name does not match …
  • java.net.ssl.SSLHandshakeException: PKIX path building failed
  • openssl s_client: handshake failure

Step‑by‑Step Troubleshooting

1. Verify the Server Certificate Chain 

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

Look for Verify return code: 0 (ok). If you see a non‑zero code, the chain is incomplete or untrusted. Fix by installing missing intermediate certificates on the server or updating the trust store.

2. Check Certificate Validity Dates 

openssl x509 -noout -dates -in server.crt
Enter fullscreen mode Exit fullscreen mode

If notAfter is in the past, renew the certificate.

3. Ensure Hostname Matching

The Common Name (CN) or Subject Alternative Name (SAN) must match the request hostname. Use:

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

If the handshake fails with hostname mismatch, update the certificate SAN entries.

4. Verify Supported Protocols & Cipher Suites

Older clients may not support TLS 1.2+ or modern ciphers. Test with:

nmap --script ssl-enum-ciphers -p 443 example.com
Enter fullscreen mode Exit fullscreen mode

Enable compatible protocols on the server (e.g., ssl_protocols TLSv1.2 TLSv1.3; in Nginx) or upgrade the client library.

5. Review Trust Store on the Client

For Java:

System.setProperty("javax.net.ssl.trustStore", "/path/to/truststore.jks");
Enter fullscreen mode Exit fullscreen mode

For Python:

import ssl
ctx = ssl.create_default_context(cafile="/etc/ssl/certs/ca-bundle.crt")
Enter fullscreen mode Exit fullscreen mode

Make sure the CA that issued the server certificate is present.

6. Diagnose with Detailed Logging

  • cURL: curl -v https://example.com
  • Java: add -Djavax.net.debug=all
  • .NET: enable System.Net.Http logging via appsettings.json

These logs reveal the exact handshake stage where the failure occurs.

Quick Fix Script

The following Bash script automates the most frequent checks and can be integrated into CI pipelines. Download the pre‑configured script here.

#!/usr/bin/env bash
HOST=$1
PORT=${2:-443}
openssl s_client -connect "$HOST:$PORT" -servername "$HOST" -showcerts <<EOF
quit
EOF
Enter fullscreen mode Exit fullscreen mode

When to Use a Patch Tool

If you manage a fleet of legacy services that cannot be immediately upgraded, you might need a temporary patch. The community‑maintained patch utility can inject missing intermediate certificates at runtime. Get the complete patch tool.

Full Repository Fix

For a comprehensive solution—including Dockerfile updates, CI/CD integration, and Terraform modules—explore the full repository. Access the full repository fix.

By systematically checking the chain, dates, hostname, protocols, and trust stores, you can eliminate the majority of SSL/TLS handshake failures. Keep your libraries up‑to‑date, automate the checks, and you’ll spend less time firefighting and more time shipping code.

Top comments (0)