Java: SSLHandshakeException Received fatal alert: handshake_failure
javax.net.ssl.SSLHandshakeException: Received fatal alert: handshake_failure 是 Java 客户端与服务端在 TLS 握手阶段“谈崩”时最常见的报错。它既可能是 JDK 太老不支持服务端要求的 TLS 1.3,也可能是双方加密套件没有交集、服务端要求客户端证书、SNI 没有正确携带,甚至是被中间的负载均衡 / WAF 直接掐断。本文按“先定位、再修复”的顺序给出可直接执行的命令与配置。
一、先看清楚错误长什么样,判断是谁拒绝了谁
典型堆栈如下(JDK 8 / 11 / 17 结构略有差异,但关键行一致):
javax.net.ssl.SSLHandshakeException: Received fatal alert: handshake_failure
at sun.security.ssl.Alert.createSSLException(Alert.java:131)
at sun.security.ssl.TransportContext.fatal(TransportContext.java:311)
at sun.security.ssl.TransportContext.fatal(TransportContext.java:254)
at sun.security.ssl.SSLTransport.decode(SSLTransport.java:168)
at sun.security.ssl.SSLSocketImpl.decode(SSLSocketImpl.java:1505)
at sun.security.ssl.SSLSocketImpl.readHandshakeRecord(SSLSocketImpl.java:1394)
关键点:Received fatal alert 表示这个 alert 是对端发过来的,编号 40(handshake_failure)。也就是说客户端的 ClientHello 已经到达服务端,服务端看完后认为“没有任何可协商的协议 / 套件 / 条件”,于是主动终止。因此排查重点在服务端视角的兼容性,而不是本地证书链校验——证书问题通常报 PKIX path building failed,是完全不同的错误。
| 报错信息 | 谁发出的信号 | 最常见原因 |
|---|---|---|
| Received fatal alert: handshake_failure (40) | 服务端 | 协议或套件无交集、要求客户端证书、SNI 不匹配 |
| No appropriate protocol (protocol is disabled or cipher suites are inappropriate) | 客户端本地 JSSE | 本地 java.security 禁用了 TLSv1/1.1,或 JDK 不支持 TLSv1.3 |
| Received fatal alert: protocol_version (70) | 服务端 | 客户端版本过低,例如 JDK 7 默认只发 TLSv1 |
| Received fatal alert: unrecognized_name (112) | 服务端 | 带了 SNI,但服务端没有对应的虚拟主机 |
| Remote host terminated the handshake | 中间设备 | 负载均衡 / WAF / 防火墙直接断连 |
二、根因剖析:handshake_failure 的 6 种真实成因
- 协议版本无交集:服务端只开 TLSv1.2 + TLSv1.3,而客户端是 JDK 6/7,默认只发 TLSv1(部分老版本甚至 SSLv3),服务端直接回 alert 40。
- JDK 不支持 TLS 1.3:JDK 8u261 之前、JDK 11.0.7 之前的 JSSE 没有 TLS 1.3 实现。如果服务端被配置成
ssl_protocols TLSv1.3;独苗,老 JDK 必然失败。 - 加密套件无交集:服务端只保留 ECDHE + AES-GCM 套件,而客户端因旧 JDK 或受限策略(JCE 限长、FIPS 模式)拿不出对应套件。
- 服务端要求客户端证书(mTLS):未配置
-Djavax.net.ssl.keyStore时,很多服务端会直接回 handshake_failure,而不是 bad_certificate。 - SNI 缺失或错误:用 IP 直连、或老 JDK 关闭了 SNI 扩展(
-Djsse.enableSNIExtension=false),服务端落到默认虚拟主机,用的是另一套证书与协议配置。 - 中间件干扰:企业 TLS 中间人代理、CDN、WAF 会重写 ClientHello 或直接拒绝特定套件。
三、第一步永远是打开握手日志
不打印握手过程就改配置,基本等于盲改。用 JSSE 自带调试开关:
# 直接启动
java -Djavax.net.debug=ssl:handshake -jar app.jar
# 输出到文件,便于 grep
java -Djavax.net.debug=ssl:handshake -jar app.jar > handshake.log 2>&1
# Tomcat:写进 setenv.sh
export CATALINA_OPTS="$CATALINA_OPTS -Djavax.net.debug=ssl:handshake"
然后在日志里抓这几行,就能定位卡在哪一步:
grep -nE "ClientHello|ServerHello|Supported Versions|cipher_suites|server_name|Alert|fatal" handshake.log
- 日志里
Supported Versions: [TLSv1.2]而服务端只认 TLSv1.3 → 版本问题。 - 有 ClientHello 但没有 ServerHello,紧跟
Received fatal alert: handshake_failure→ 服务端拒绝,看cipher_suites列表与服务端是否匹配。 - ClientHello 里缺少
server_name扩展 → SNI 问题。 - 完全看不到 ClientHello 就报错 → 本地 JSSE 在发数据前就失败了(协议被禁用)。
同时从服务端外部验证一遍,排除“只有 Java 有问题”的错觉:
openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_2 </dev/null
openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_3 </dev/null
nmap --script ssl-enum-ciphers -p 443 api.example.com
curl -v --tlsv1.2 --tls-max 1.2 https://api.example.com/health
四、JDK 版本与 TLS 支持对照表
先确认运行版本,别拿开发机的 JDK 21 去推断生产容器的 JDK 8u151:
java -version
java -XshowSettings:properties -version 2>&1 | grep -E "java.version|java.home|java.vendor"
| JDK 版本 | 默认启用协议 | TLS 1.3 | 备注 |
|---|---|---|---|
| JDK 6 / 7 | TLSv1(6 还含 SSLv3) | 不支持 | 必须显式开 TLSv1.2 且服务端保留 TLSv1.2 |
| JDK 8 < 8u31 | TLSv1 | 不支持 | 需 -Dhttps.protocols=TLSv1.2 |
| JDK 8u31 – 8u260 | TLSv1、TLSv1.1、TLSv1.2 | 不支持 | 8u161+ 默认启用无限强度加密策略 |
| JDK 8u261 – 8u3xx | TLSv1.2、TLSv1.3 | 支持 | 生产上最常见的“刚好够用”版本 |
| JDK 11.0.0 – 11.0.6 | TLSv1.2 | 不支持 | 需升级到 11.0.7+ |
| JDK 11.0.7+ / 17 / 21 | TLSv1.2、TLSv1.3 | 支持 | 推荐目标版本 |
注意:TLS 1.3 的加密套件由 JSSE 内置实现,jdk.tls.client.cipherSuites 对它无效;想调整 TLS 1.3 套件要用 jdk.tls.client.cipherSuites 之外的方式(服务端 jdk.tls.server.cipherSuites 同样只作用于 TLS 1.2 及以下)。
五、客户端侧修复:显式指定协议与套件
方式 1:系统属性(最省事,注意作用范围)
# 只影响 HttpsURLConnection
-Dhttps.protocols=TLSv1.2,TLSv1.3
# 影响整个 JSSE 栈(推荐)
-Djdk.tls.client.protocols=TLSv1.2,TLSv1.3
方式 2:代码里显式设置(适用于 SSLSocket / 自定义 SSLContext)
SSLContext ctx = SSLContext.getInstance("TLS");
ctx.init(null, null, null);
try (SSLSocket s = (SSLSocket) ctx.getSocketFactory()
.createSocket("api.example.com", 443)) {
s.setEnabledProtocols(new String[]{"TLSv1.2", "TLSv1.3"});
s.startHandshake();
}
方式 3:Java 11+ HttpClient
HttpClient client = HttpClient.newBuilder()
.sslContext(ctx)
.version(HttpClient.Version.HTTP_2)
.build();
方式 4:Apache HttpClient 4.x,不要用已废弃的 SSLProtocolSocketFactory,改用:
SSLConnectionSocketFactory f = new SSLConnectionSocketFactory(
ctx, new String[]{"TLSv1.2", "TLSv1.3"}, null,
SSLConnectionSocketFactory.getDefaultHostnameVerifier());
如果确认必须回退到 TLSv1.1(仅限内网遗留系统),要同时修改 java.security 中的 jdk.tls.disabledAlgorithms,并注意必须完整重写整行,而不是只追加一项,否则会连带放开其它不该放开的算法。
六、服务端侧修复:保留兼容协议,别把门关死
Nginx
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384;
ssl_prefer_server_ciphers on;
ssl_session_cache shared:SSL:10m;
注意 ssl_ciphers 只对 TLS 1.2 及以下生效;TLS 1.3 套件需 OpenSSL 1.1.1+ 的 ssl_conf_command Ciphersuites ...。
Apache httpd
SSLProtocol all -SSLv3 -TLSv1 -TLSv1.1
SSLCipherSuite ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256
SSLHonorCipherOrder off
Tomcat Connector
<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
SSLEnabled="true" scheme="https" secure="true"
sslEnabledProtocols="TLSv1.2,TLSv1.3"
ciphers="TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384" />
改完务必用 openssl s_client 或 nmap --script ssl-enum-ciphers 复核实际生效的协议,而不是只看配置文件——很多事故是前面还有一层 LB / CDN 在跑老配置。
七、容易被忽略的其他诱因
- mTLS:服务端
ssl_verify_client on;时,客户端未提供证书常表现为 handshake_failure。用-Djavax.net.ssl.keyStore=client.p12 -Djavax.net.ssl.keyStorePassword=***补上。 - SNI 被关闭:检查是否有人加了
-Djsse.enableSNIExtension=false;用 IP 直连也会丢 SNI。 - ALPN 不匹配:通常报
no application protocol(alert 120),但在部分网关会被吞成 handshake_failure。 - 证书算法被禁用:SHA-1 签名、1024 位 RSA 在 JDK 8u161+ 的
jdk.certpath.disabledAlgorithms下会被拒。 - 中间人代理:公司网络替换证书后,Java 侧需要把企业根证书导入
cacerts。 - 连接池 / 长连接:服务端升级 TLS 配置后,客户端复用了旧会话,重启客户端进程或清空连接池即可。
八、错误信息对照表与 5 步排查法
| 完整错误信息 | 含义 | 处理方向 |
|---|---|---|
| Received fatal alert: handshake_failure | 服务端拒绝 ClientHello | 对齐协议版本与套件、检查 mTLS 与 SNI |
| javax.net.ssl.SSLHandshakeException: No appropriate protocol (protocol is disabled or cipher suites are inappropriate) | 本地 JSSE 在发数据前就失败 | 检查 jdk.tls.disabledAlgorithms 与 JDK 版本 |
| Received fatal alert: protocol_version | 协议版本不匹配 | 升级 JDK 或服务端补开 TLSv1.2 |
| Received fatal alert: unrecognized_name | SNI 指向了不存在的虚拟主机 | 核对域名与 server_name |
| PKIX path building failed: unable to find valid certification path to requested target | 证书链不完整 / 根证书未信任 | 导入 CA,补齐中间证书 |
| java.security.cert.CertificateException: No subject alternative names present | 证书 SAN 不含该域名 | 换证书或改用正确域名 |
| SSLHandshakeException: Remote host terminated the handshake | 对端直接断开,没发 alert | 查 LB / WAF 日志与网络 ACL |
| Received fatal alert: insufficient_security | 算法强度不足 | 升级 JDK 加密策略,换更强套件 |
推荐的固定排查顺序:
java -version确认客户端 JDK 与 TLS 1.3 支持情况。-Djavax.net.debug=ssl:handshake抓 ClientHello 的 Supported Versions 与 cipher_suites。openssl s_client -servername ... -tls1_2 / -tls1_3分别验证服务端两侧协议。- 对比第 2、3 步结果,找出交集为空的维度(版本 / 套件 / SNI / 客户端证书)。
- 只改一个维度并复测,避免同时改 JDK 与服务端导致无法归因。
九、FAQ
Q1:升级 JDK 就一定能解决 handshake_failure 吗?
不一定。升级只能解决“客户端不支持 TLS 1.3 / 新套件”这一类问题;如果是服务端要求客户端证书或 SNI 不匹配,升级 JDK 毫无作用。
Q2:为什么 curl 和浏览器都正常,只有 Java 报错?
因为 JSSE 的默认协议与套件集合和 OpenSSL 不同,而且 Java 有自己的 cacerts 信任库与 java.security 禁用算法列表。用 -Djavax.net.debug 对比两边的 ClientHello 即可看出差异。
Q3:-Dhttps.protocols 和 -Djdk.tls.client.protocols 有什么区别?
前者只影响 HttpsURLConnection;后者作用于整个 JSSE 栈,包括 SSLSocket、HttpClient、各类第三方 HTTP 客户端。生产上优先用后者。
Q4:能不能直接开启 TLSv1 来兼容老客户端?
技术上可以,但 PCI DSS 早已禁止,且主流浏览器与服务端框架已移除支持。正确做法是升级客户端,或在前置网关上单独开一条仅内网可达的兼容通道。
Q5:日志里看到 ClientHello 但没有 ServerHello,说明什么?
说明请求已发出,服务端(或中间设备)没有回应任何握手消息就断开,或回了 alert。重点看同一时刻的 alert 行与网络侧设备日志。
Q6:TLS 1.3 下 jdk.tls.client.cipherSuites 为什么不起作用?
TLS 1.3 的套件由 JSSE 内置固定集合管理,该属性只对 TLS 1.2 及以下生效。要限制 TLS 1.3 套件需通过 jdk.tls.disabledAlgorithms 或服务端配置实现。
Q7:改完配置后仍然报同样的错,怎么确认配置生效了?
用 openssl s_client -connect host:443 -servername host 看实际协商结果,并在客户端加 -Djavax.net.debug=ssl:handshake 确认新的 Supported Versions 已出现在 ClientHello 中。若两边都变了还失败,基本可以锁定在中间网络设备上。