跳到主要内容

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 加密策略,换更强套件

推荐的固定排查顺序:

  1. java -version 确认客户端 JDK 与 TLS 1.3 支持情况。
  2. -Djavax.net.debug=ssl:handshake 抓 ClientHello 的 Supported Versions 与 cipher_suites。
  3. openssl s_client -servername ... -tls1_2 / -tls1_3 分别验证服务端两侧协议。
  4. 对比第 2、3 步结果,找出交集为空的维度(版本 / 套件 / SNI / 客户端证书)。
  5. 只改一个维度并复测,避免同时改 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 中。若两边都变了还失败,基本可以锁定在中间网络设备上。