跳到主要内容

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 也连不上 → 服务端配置问题。