Java SSLHandshakeException: Received fatal alert: handshake_failure 完整排查与修复指南
一、这个错误到底在说什么
Received fatal alert: handshake_failure 是 服务端(或中间的负载均衡、WAF、CDN)主动发回的 TLS alert,含义是“我在你发来的 ClientHello 里找不到能接受的『协议版本 + 加密套件』组合”。它不是证书错误,也不是网络不通——TCP 三次握手已经完成,TLS 协商才刚开头就崩了。
典型堆栈长这样:
javax.net.ssl.SSLHandshakeException: Received fatal alert: handshake_failure
at sun.security.ssl.Alerts.getSSLException(Alerts.java:192)
at sun.security.ssl.SSLSocketImpl.fatal(SSLSocketImpl.java:1949)
at sun.security.ssl.Handshaker.fatalSE(Handshaker.java:302)
at sun.security.ssl.ClientHandshaker.serverHello(ClientHandshaker.java:1043)
at com.example.HttpClient.get(HttpClient.java:57)
Caused by: javax.net.ssl.SSLHandshakeException: Received fatal alert: handshake_failure
定位失败点有个简单口诀:
- ClientHello 之后立刻失败 → 协议版本或加密套件没有交集(本文重点)。
- 走到 Certificate 之后才失败 → 证书链、信任库、主机名校验问题。
- CertificateRequest 之后失败 → 双向认证 mTLS,客户端没提供证书。
二、三类根本原因对照
| 原因分类 | 典型日志特征 | 修复方向 |
|---|---|---|
| 协议版本无交集 | ClientHello 后立刻出现 alert;openssl -tls1_3 失败但 -tls1_2 成功 |
升级 JDK,或服务端启用 TLSv1.2 |
| 加密套件无交集 | 双方都支持 TLS1.2 仍失败;用 -cipher 指定某个 ECDHE 套件后成功 |
服务端补 ECDHE 套件,去掉仅 CBC/3DES 的老配置 |
| 证书链 / 信任库 | 失败发生在 Certificate 之后,伴随 PKIX path building failed |
导入 CA、补全中间证书 |
| mTLS 缺少客户端证书 | 收到 CertificateRequest 后失败 | 配置 keystore 与 javax.net.ssl.keyStore |
| 中间设备拦截 | 抓包显示 alert 来源 IP 不是后端服务器 | 检查 LB / WAF / CDN 的 TLS 策略 |
三、第一步:打开 SSL 握手调试日志
不要猜,先看日志。JSSE 的调试开关是 javax.net.debug,ssl:handshake 是日志量最合适的级别:
# 推荐:只打印握手过程
java -Djavax.net.debug=ssl:handshake -jar app.jar > handshake.log 2>&1
# 需要看套件、证书、记录层细节时
java -Djavax.net.debug=ssl,handshake,record -jar app.jar > handshake.log 2>&1
# 只看关键行
grep -nE "ClientHello|ServerHello|alert|protocol|cipher" handshake.log | head -50
日志里能直接读出结论:
*** ClientHello, TLSv1.2
...
*** ServerHello, TLSv1.2
...
javax.net.ssl.SSLHandshakeException: Received fatal alert: handshake_failure
如果 ClientHello 之后直接是 alert,看两处:ClientHello 里的 cipher_suites 列表和服务端返回的 selected cipher。服务端一个都没选,就会回 handshake_failure。
同时抓包交叉验证 alert 的真实来源:
tcpdump -i any -w tls.pcap port 443
用 Wireshark 打开,看 Alert 报文的源 IP——如果来自负载均衡而不是后端应用,问题就不在应用服务器配置上。
四、JDK 版本与 TLS 支持对照表
“JDK 太老不支持 TLS 1.3”是最高频原因。先用命令确认版本:
java -version 2>&1
java -XshowSettings:properties -version 2>&1 | grep -iE "java.version|java.home"
再确认当前 JVM 实际启用的协议列表:
jrunscript -e "var c=javax.net.ssl.SSLContext.getInstance('TLS');c.init(null,null,null);print('default: '+c.getDefaultSSLParameters().getProtocols().join(','));print('supported: '+c.getSupportedSSLParameters().getProtocols().join(','))"
(jrunscript 在 JDK 15 之后被移除,新版本请用一段 10 行的 Java 小程序调用同样的 API。)
| JDK 版本 | TLS 1.0 / 1.1 | TLS 1.2 | TLS 1.3 | 说明 |
|---|---|---|---|---|
| JDK 6 及更早 | 支持 | 6u121+ 有限支持 | 不支持 | 早已 EOL,必须升级 |
| JDK 7 | 支持 | 支持,部分版本需显式开启 | 不支持 | 已 EOL |
| JDK 8 < 8u261 | 支持 | 默认启用 | 不支持 | 连 TLS 1.3 服务端会失败 |
| JDK 8u261 ~ 8u291 | 支持 | 默认启用 | 已回移植,部分构建需显式开启 | 可用 -Djdk.tls.client.protocols=TLSv1.3 验证 |
| JDK 8u291+ | 默认禁用 | 默认启用 | 支持 | 需连老服务端时要放开 jdk.tls.disabledAlgorithms |
| JDK 11.0.3 ~ 11.0.6 | 默认启用 | 默认启用 | 支持 | 建议升到 11.0.7+ |
| JDK 11.0.7+ | 默认启用 | 默认启用 | 默认启用,稳定性更好 | 生产推荐最低版本 |
| JDK 17 / 21(LTS) | 默认禁用 | 默认启用 | 默认启用 | 新项目首选 |
注意:具体默认行为随更新版本变化,以 $JAVA_HOME/conf/security/java.security 里的 jdk.tls.disabledAlgorithms 为准。
五、客户端修复:代码与 JVM 参数
方式一:JVM 启动参数(最快验证)
java -Djdk.tls.client.protocols=TLSv1.2,TLSv1.3
-Dhttps.protocols=TLSv1.2,TLSv1.3
-Djavax.net.debug=ssl:handshake
-jar app.jar
两个属性的区别很关键:https.protocols 只影响 HttpsURLConnection;jdk.tls.client.protocols 影响 JSSE 默认 SSLContext,覆盖面更广。Apache HttpClient、OkHttp、Netty 等往往有自己的 SSL 配置层,未必吃这两个属性。
方式二:代码里显式指定(最可靠)
// 对 HttpsURLConnection 及其封装库生效
System.setProperty("https.protocols", "TLSv1.2,TLSv1.3");
System.setProperty("https.cipherSuites",
"TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384");
// 直接控制 SSLSocket,不受任何框架封装影响
SSLContext ctx = SSLContext.getInstance("TLS");
ctx.init(null, null, null);
SSLSocket socket = (SSLSocket) ctx.getSocketFactory()
.createSocket("api.example.com", 443);
socket.setEnabledProtocols(new String[]{"TLSv1.2", "TLSv1.3"});
socket.startHandshake();
方式三:连老服务端时放开协议禁用
java -Djdk.tls.disabledAlgorithms="RC4, DES, MD5withRSA, DH keySize < 1024, EC keySize < 224" -jar app.jar
这是把 TLSv1/TLSv1.1 从黑名单里拿掉,属于临时兼容手段,务必配合升级计划,不要长期留在生产。
六、服务端修复:Nginx / Apache / Tomcat 配置
Nginx
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305;
ssl_prefer_server_ciphers on;
# TLS 1.3 套件需 nginx 1.19.4+ 且 OpenSSL 1.1.1+
ssl_ciphersuites TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256;
Apache httpd
SSLProtocol all -SSLv2 -SSLv3 -TLSv1 -TLSv1.1
SSLCipherSuite HIGH:!aNULL:!MD5:!3DES
SSLHonorCipherOrder on
Tomcat server.xml
<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
SSLEnabled="true"
sslProtocol="TLS"
sslEnabledProtocols="TLSv1.2,TLSv1.3"
ciphers="TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384" />
Spring Boot 内嵌 Tomcat
server.ssl.enabled-protocols=TLSv1.2,TLSv1.3
server.ssl.ciphers=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
改完别忘了 nginx -t && nginx -s reload 或重启 Tomcat,并用第七节的 openssl 命令复验。
七、用 openssl / nmap 验证套件与证书链
先确认服务端到底支持什么:
# 默认协商结果
openssl s_client -connect api.example.com:443 -servername api.example.com </dev/null
# 分别探测 TLS 1.2 / 1.3
openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_2 </dev/null | grep -E "Protocol|Cipher"
openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_3 </dev/null | grep -E "Protocol|Cipher"
# 枚举全部可用套件
nmap --script ssl-enum-ciphers -p 443 api.example.com
如果 -tls1_3 报 handshake failure 而 -tls1_2 成功,说明服务端压根没开 TLS 1.3——客户端怎么配都没用,得改服务端。
检查证书链是否完整(中间证书缺失是“浏览器能开、Java 打不开”的常见元凶):
openssl s_client -connect api.example.com:443 -showcerts </dev/null 2>/dev/null | openssl x509 -noout -subject -dates -ext subjectAltName
检查 Java 信任库是否包含对应 CA:
keytool -list -v -keystore "$JAVA_HOME/lib/security/cacerts" -storepass changeit | grep -i "your-ca-name"
需要补证书时:
keytool -importcert -alias my-ca -file ca.crt -keystore truststore.jks -storepass changeit -noprompt
java -Djavax.net.ssl.trustStore=/opt/app/truststore.jks -Djavax.net.ssl.trustStorePassword=changeit -jar app.jar
八、故障排查速查表(真实报错信息)
| 报错信息 | 含义 | 处理 |
|---|---|---|
Received fatal alert: handshake_failure |
服务端找不到共同协议/套件,或缺客户端证书 | 按本文三~六节排查 |
Received fatal alert: protocol_version |
服务端不支持客户端提供的最高协议版本 | 升级 JDK 或服务端开 TLSv1.2 |
Received fatal alert: unrecognized_name |
SNI 不被识别 | 加 -Djsse.enableSNIExtension=true |
No appropriate protocol (protocol is disabled or cipher suites are inappropriate) |
客户端本地把协议/套件禁用了 | 调整 jdk.tls.disabledAlgorithms |
Server chose TLSv1, but that protocol version is not enabled or not supported by the client |
客户端禁用 TLSv1,服务端却选了它 | 服务端配置升级到 TLSv1.2+ |
sun.security.validator.ValidatorException: PKIX path building failed |
信任库缺少根 CA 或中间证书不全 | keytool -importcert 导入 |
CertificateException: No subject alternative names present |
证书 SAN 与访问域名不匹配 | 换证书,勿用关闭校验绕过 |
javax.net.ssl.SSLException: Unsupported or unrecognized SSL message |
对端端口不是 TLS(如直连 8080 HTTP 端口) | 确认端口与代理设置 |
NoSuchAlgorithmException: TLSv1.3 SSLContext not available |
JDK 太老,无 TLS 1.3 实现 | 升级到 8u261+ / 11.0.7+ / 17 |
Remote host closed connection during handshake |
服务端直接断连,常见于 LB 健康检查或防火墙 | 查中间设备策略与后端存活状态 |
九、FAQ
Q1:升级 JDK 还是改服务端配置?
优先升级 JDK。TLS 1.0/1.1 已全面淘汰,把客户端升到 8u261+ 或 11.0.7+ 是唯一可持续方案;只有在无法升级时,才临时让服务端兼容老协议。
Q2:为什么浏览器能访问,Java 客户端不行?
浏览器自带完整根证书库、支持 TLS 1.3、自动补全中间证书。Java 用的是 $JAVA_HOME/lib/security/cacerts,且协议版本受 JDK 限制。三类差异:协议版本、信任库、SNI。
Q3:https.protocols 和 jdk.tls.client.protocols 有什么区别?
前者只作用于 HttpsURLConnection;后者作用于 JSSE 默认 SSLContext,影响面更广。两者都设上最保险,但用了自建 SSLContext 的框架仍需单独配置。
Q4:测试环境正常,生产报 handshake_failure?
多半是两边 JDK 版本不同,或生产前面多了一层 LB/WAF 把协议限制得更死。对比两边的 java -version 与 openssl s_client 输出即可定位。
Q5:能不能直接信任所有证书绕过?
技术上可以(自定义 X509TrustManager),但会彻底失去中间人攻击防护,且不能解决 handshake_failure——那是协议/套件问题,不是证书问题。生产环境禁止。
Q6:升级 JDK 后反而连不上老服务端?
新 JDK 默认禁用了 TLSv1/TLSv1.1。要么升级服务端,要么临时用 -Djdk.tls.disabledAlgorithms 放开,并把它列入技术债清单。
Q7:怎么快速判断是客户端还是服务端的问题?
用 openssl s_client -tls1_2 和 -tls1_3 各测一次。openssl 能连、Java 连不上 → 客户端 JDK 或信任库问题;openssl 也连不上 → 服务端配置问题。