Introduction

SSL handshake fails when client and server have no common protocol version. This guide provides step-by-step diagnosis and resolution.

Symptoms

Typical error output:

bash
SSL handshake failed: no common protocol version
Client supports: TLSv1.2 TLSv1.3
Server supports: TLSv1.0 TLSv1.1

Common Causes

  1. 1.Certificate chain not properly configured
  2. 2.Certificate expired or not yet valid
  3. 3.Hostname does not match certificate
  4. 4.Protocol or cipher mismatch

Step-by-Step Fix

Step 1: Check Current State

bash
openssl s_client -connect example.com:443 -servername example.com
openssl x509 -in certificate.crt -text -noout
echo | openssl s_client -connect example.com:443 2>/dev/null | openssl x509 -noout -dates

Step 2: Identify Root Cause

bash
openssl s_client -connect example.com:443 -showcerts
openssl x509 -in cert.pem -text -noout
curl -vI https://example.com

Step 3: Apply Primary Fix

```bash # Primary fix: Check certificate chain openssl s_client -connect example.com:443 -showcerts

# Verify certificate openssl verify -CAfile chain.crt server.crt

# Restart web server systemctl restart nginx ```

Step 4: Apply Alternative Fix

```bash # Alternative fix: Update configuration cat /etc/nginx/sites-enabled/default | grep ssl

# Test configuration nginx -t

# Check OCSP openssl ocsp -issuer chain.crt -cert server.crt -url http://ocsp.example.com -resp_text ```

Step 5: Verify the Fix

bash
openssl s_client -connect example.com:443 -servername example.com
curl -vI https://example.com
# Should show successful TLS handshake

Common Pitfalls

  • Not including intermediate certificates in chain
  • Forgetting to restart web server after cert update
  • Using wrong certificate format for server
  • Not testing with online SSL checker

Best Practices

  • Use certificate monitoring for expiration alerts
  • Implement HSTS for HTTPS enforcement
  • Regularly scan for SSL vulnerabilities
  • Use automated certificate renewal with ACME
  • SSL Handshake Failed
  • HTTPS Connection Refused
  • Mixed Content Warning
  • SSL Protocol Error