SSL: handshake failure / protocol error
ID: networking/ssl-protocol-error
Version Compatibility
| Version | Status | Introduced | Deprecated | Notes |
|---|---|---|---|---|
| 3 | active | — | — | — |
Root Cause
The SSL/TLS handshake between client and server failed due to a protocol negotiation error. This typically occurs when there is no common TLS version, cipher suite, or when the handshake message sequence is corrupted.
genericWorkarounds
-
88% success Align TLS version and cipher suite support between client and server
1. Check server supported protocols: nmap --script ssl-enum-ciphers -p 443 host 2. Check client capabilities: openssl ciphers -v 3. Set minimum TLS version on client: -tls1_2 or -tls1_3 flag in openssl s_client 4. Configure cipher suites: openssl s_client -connect host:443 -cipher 'ECDHE+AESGCM' 5. For OpenSSL 3.x, ensure security level is appropriate: @SECLEVEL=1 for legacy compatibility
-
85% success Update OpenSSL and server software to support TLS 1.3
1. Check current OpenSSL version: openssl version 2. Update OpenSSL: apt update && apt install -y openssl libssl-dev 3. Update server software (nginx, apache, etc.) to versions supporting TLS 1.3 4. Configure server for TLS 1.2+ only: ssl_protocols TLSv1.2 TLSv1.3; 5. Test handshake: openssl s_client -connect host:443 -tls1_3
Dead Ends
Common approaches that don't work:
-
Force the client to use SSL 3.0 or TLS 1.0 to maximize compatibility
90% fail
SSL 3.0 is vulnerable to POODLE and TLS 1.0 to BEAST. Most modern servers disable these protocols entirely, so forcing them will result in the same handshake failure or a different error. OpenSSL 3.x has removed SSL 3.0 support by default.
-
Disable all cipher suite restrictions to allow any cipher
75% fail
Setting cipher strings to ALL or COMPLEMENTOFALL enables insecure ciphers that servers may still reject. OpenSSL 3.x has deprecated many legacy ciphers, and enabling them requires loading the legacy provider which introduces security risks.