跳到主要内容

Java 报错 Received fatal alert: protocol_version:从 TLS 握手原理到修复的完整指南

一、错误含义:protocol_version 到底是谁拒绝了谁

Received fatal alert: protocol_version 不是证书错误,也不是密码套件错误,而是 JSSE 把对端发来的 TLS 告警原样翻译后的结果。alert 由对端发出(通常是服务端、Nginx、F5、API 网关或 CDN),含义是:你在 ClientHello 里提议的协议版本,我一个都不接受。

典型堆栈长这样:

javax.net.ssl.SSLHandshakeException: Received fatal alert: protocol_version
    at sun.security.ssl.Alerts.getSSLException(Alerts.java:192)
    at sun.security.ssl.Alerts.getSSLException(Alerts.java:154)
    at sun.security.ssl.SSLSocketImpl.recvAlert(SSLSocketImpl.java:2020)
    at sun.security.ssl.SSLSocketImpl.readRecord(SSLSocketImpl.java:1123)
Caused by: javax.net.ssl.SSLException: Received fatal alert: protocol_version

因此“升级 JDK”只是解法之一,真正的解法只有一句话:让客户端启用的协议集合与服务端接受的协议集合产生交集。常见的三种“无交集”形态:

  1. 客户端最高只到 TLS 1.2,服务端按安全基线收敛成 ssl_protocols TLSv1.3;;
  2. 客户端只发 TLS 1.0/1.1(老 JDK,或 jdk.tls.disabledAlgorithms 误禁了 TLSv1.2),服务端已关闭 1.0/1.1;
  3. 代码或框架把协议写死成单一版本(如只给 TLSv1.2),而服务端只开 TLS 1.3。

还有一种“看起来不一样、本质一样”的现象:日志里不是 protocol_version,而是 Remote host closed connection during handshake 或 Unsupported or unrecognized SSL message。这往往是因为老客户端无法解析 TLS 1.3 服务端返回的告警记录,直接当成连接被关闭。排查思路完全相同。

二、快速诊断:三条命令确认双方协议能力

1. 确认 JDK 版本与 JVM 实际启用的协议

java -version
java -XshowSettings:properties -version 2>&1 | grep -E 'java.version|java.home'
# JDK 9+ 可直接用 jshell 打印默认启用协议
jshell -q <<'EOF'
System.out.println(java.util.Arrays.toString(javax.net.ssl.SSLContext.getDefault().getDefaultSSLParameters().getProtocols()));
EOF

JDK 8 没有 jshell,可写一个 20 行的 Java 小程序调用 getDefaultSSLParameters().getProtocols(),或直接用 -Djavax.net.debug=ssl:handshake 看 ClientHello 里的 versions 列表。

2. 确认服务端实际接受的协议

# 逐协议探测,能握手成功会输出证书链
openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_2 </dev/null | head -20
openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_3 </dev/null | head -20

# 一次性枚举协议与套件(需安装 nmap)
nmap --script ssl-enum-ciphers -p 443 api.example.com

失败时会看到 alert protocol version、no protocols available 或 handshake failure。务必带上 -servername,否则 SNI 虚拟主机可能返回另一套完全不同的配置,把你带到错误的方向。

3. 打开 JSSE 握手日志

java -Djavax.net.debug=ssl:handshake:verbose -jar app.jar 2>&1 | grep -E 'ClientHello|versions|Alert'

日志会明确写出客户端提议了哪些版本、服务端回了什么告警。这一步能直接区分“协议不匹配”与“证书/套件不匹配”。

三、根因分析:协议集合没有交集

TLS 握手第一步,客户端在 ClientHello 的 supported_versions 扩展(TLS 1.2 及以前则是 legacy_version)中列出自己支持的版本,服务端从中挑一个双方都支持的;一个都挑不出来,服务端立刻回 fatal alert: protocol_version 并断开连接。

线上最常见的触发场景:

  • 客户端太老:JDK 6/7 或 JDK 8 早期版本,客户端最高只到 TLS 1.2,而服务端已只开 TLS 1.3。
  • 客户端被裁剪:安全加固脚本把 jdk.tls.disabledAlgorithms 写成了包含 TLSv1.2 的列表,客户端实际只剩 TLS 1.0/1.1。
  • 代码写死:System.setProperty("https.protocols", "TLSv1.2") 只留一个版本,服务端又恰好停用了它。
  • 中间层不一致:Java 握手的是 API 网关 / F5 / CDN,而不是最终后端,网关的 TLS 策略与后端不同步。
  • 服务端被过度收敛:运维按“只允许 TLS 1.3”加固,但存量客户端里还有大量 8u 早期版本。

四、修复方案 A:升级 JDK 小版本,直接获得 TLS 1.3

JDK 8u261 起默认启用 TLS 1.3,这是成本最低、收益最直接的做法。JDK 11/17/21 更是默认只保留 TLS 1.2 与 1.3。

# 先看清当前版本与安装路径
java -version
readlink -f $(which java)

# 建议升级到 8u261+,或直接上 LTS
sudo apt install openjdk-17-jdk
# 或使用 SDKMAN
sdk install java 17.0.11-tem

升级时容易踩的三个坑:

  • 改了但没生效:机器上有多个 JDK,JAVA_HOME 与 PATH 指向不同版本。用 java -XshowSettings:properties -version 2>&1 | grep java.home 确认。
  • 容器镜像没重建:Dockerfile 里固定了旧基础镜像,本地升级无济于事。
  • 升级后反而更糟:JDK 11+ 默认禁用 TLS 1.0/1.1,如果对端只支持老协议,会报同样的 protocol_version。此时应该升级服务端,而不是降级客户端。

五、修复方案 B:显式指定协议版本(注意两个属性别混用)

这两个属性经常被当成同义词,实际上作用范围差别很大:

  • https.protocols:只影响 HttpsURLConnection(以及基于它的老式客户端)。对 SSLSocket、Netty、OkHttp、Apache HttpClient 4.x、gRPC 完全不生效。
  • jdk.tls.client.protocols:影响 JSSE 全局默认 SSLContext,作用面更广(JDK 8u31+ 支持),是更可靠的选择。
# 推荐:JVM 启动参数,避免 System.setProperty 散落在代码里
java -Djdk.tls.client.protocols=TLSv1.2,TLSv1.3 -jar app.jar

# 仅 HttpsURLConnection 场景的兼容写法
java -Dhttps.protocols=TLSv1.2,TLSv1.3 -jar app.jar

代码方式(推荐精确到单个连接,影响面可控):

SSLContext ctx = SSLContext.getInstance("TLS");
ctx.init(null, null, null);
SSLSocketFactory f = ctx.getSocketFactory();
try (SSLSocket s = (SSLSocket) f.createSocket("api.example.com", 443)) {
    s.setEnabledProtocols(new String[]{"TLSv1.2", "TLSv1.3"});
    s.startHandshake();
    System.out.println("negotiated: " + s.getSession().getProtocol());
}

Apache HttpClient 4.5 需要显式构造 SocketFactory:

SSLConnectionSocketFactory sf = new SSLConnectionSocketFactory(
    ctx, new String[]{"TLSv1.2", "TLSv1.3"}, null,
    SSLConnectionSocketFactory.getDefaultHostnameVerifier());
CloseableHttpClient client = HttpClients.custom().setSSLSocketFactory(sf).build();

提醒:不要为了“先跑通”把 TLSv1、SSLv3 加回列表,那等于直接放弃安全基线,且下一次安全扫描就会找上门。

六、修复方案 C:检查 jdk.tls.disabledAlgorithms 与服务端 ssl_protocols

客户端侧:找到真正生效的 java.security

readlink -f $(which java)
grep -n -A3 'jdk.tls.disabledAlgorithms' $JAVA_HOME/conf/security/java.security
# JDK 8 的路径是 $JAVA_HOME/jre/lib/security/java.security

如果看到类似 jdk.tls.disabledAlgorithms=SSLv3, TLSv1, TLSv1.1, TLSv1.2, RC4, DES, ...,说明 TLSv1.2 被误伤——它本不该出现在这个列表里。

# 不改文件,临时验证是否是该属性导致(整体覆盖,不是追加)
java -Djdk.tls.disabledAlgorithms="SSLv3, TLSv1, TLSv1.1, RC4, DES, MD5withRSA, 3DES_EDE_CBC" -jar app.jar

注意两点:该属性是整体覆盖,漏写的项等于放开,生产环境务必走变更评审;修改 java.security 后必须重启 JVM,容器环境要重建镜像,否则下次发布立刻回滚。

服务端侧:让配置真正形成交集

# Nginx
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-CHACHA20-POLY1305';
nginx -t && systemctl reload nginx

# Apache httpd
SSLProtocol -all +TLSv1.2 +TLSv1.3

# Tomcat server.xml
<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
           SSLEnabled="true" sslEnabledProtocols="TLSv1.2,TLSv1.3" />

迁移原则:服务端把 TLSv1.2 保留为兼容底线,客户端逐步升到 8u261+/11+/17+,确认存量客户端全部支持 1.2 之后,再评估是否关闭 1.2 并只留 1.3。

七、JDK 版本与默认协议对照表

JDK 版本 客户端默认启用协议 是否支持 TLS 1.3 建议动作
JDK 6 及更早 TLS 1.0(SSLv3 亦可用) 否 必须升级,无法与现代服务端握手
JDK 7(早期) TLS 1.0,1.1/1.2 需显式开启 否 升级;临时在代码里 setEnabledProtocols 指定 TLSv1.2
JDK 7u95+ / 8(< 8u31) TLS 1.0 / 1.1 / 1.2 否 显式指定 TLSv1.2,尽快升级
JDK 8u31 – 8u260 TLS 1.0 / 1.1 / 1.2 实现存在但默认关闭 升级到 8u261+,或显式开启 TLS 1.3
JDK 8u261+ TLS 1.0 / 1.1 / 1.2 / 1.3 是(默认) 通常无需改动,重点检查 disabledAlgorithms
JDK 11 / 17 / 21 TLS 1.2 / 1.3(1.0、1.1 默认禁用) 是 确认服务端至少支持 TLS 1.2

读表要点:新 JDK 不代表“更兼容”,而是“更安全”。JDK 11+ 默认禁用 TLS 1.0/1.1,遇到只支持老协议的服务端,同样会抛 protocol_version。如果你的 11.0.x 仍然显示 TLSv1 可用,先检查 java.security 是否被旧镜像覆盖。

八、故障排查:真实错误信息与对应处置

1. javax.net.ssl.SSLHandshakeException: Received fatal alert: protocol_version

最典型形态,双方协议集合无交集。按第二节确认双方能力,按第四/五/六节制造交集即可。

2. javax.net.ssl.SSLException: Received fatal alert: handshake_failure

版本对上了,但密码套件、证书链或客户端认证不匹配。此时应检查 ssl_ciphers、证书是否过期、是否需要 mTLS,而不是继续折腾协议版本。

3. javax.net.ssl.SSLHandshakeException: Remote host closed connection during handshake

对端直接断开,常见于老客户端遇到只开 TLS 1.3 的服务端,或中间设备重置连接。开 -Djavax.net.debug=ssl:handshake 看是否发出 ClientHello 后毫无响应,再用 openssl 逐协议探测定位。

4. javax.net.ssl.SSLException: Unsupported or unrecognized SSL message

你连的端口根本不是 TLS 端口——比如把 80 当 443,或经过 HTTP 代理却没走 CONNECT。先 curl -v https://host:port/ 确认。

5. java.security.cert.CertificateException: No subject alternative names present / PKIX path building failed

证书问题,与协议版本无关。它们经常和 SSLHandshakeException 出现在同一段堆栈里,别被误导。

6. 服务端日志:no protocols available / SSL_do_handshake() failed … wrong version number

Nginx/OpenSSL 侧记录,对应客户端发来的版本不被 ssl_protocols 接受。用 openssl s_client -tls1_2 复现,再逐行对照配置。

7. 只在容器或某一台机器上复现

镜像内 JDK 版本不同、JAVA_HOME 指向旧 JDK,或镜像里替换过 java.security。用 java -XshowSettings:properties -version 打印实际生效路径,比猜快得多。

九、FAQ 常见问题

Q1:我已经设置了 https.protocols,为什么还是报 protocol_version?

因为该属性只对 HttpsURLConnection 生效。如果你用的是 OkHttp、Netty、Apache HttpClient、gRPC 或自建 SSLSocket,它根本不读这个属性。改用 jdk.tls.client.protocols,或在对应客户端里显式设置 enabledProtocols。

Q2:服务端只开 TLS 1.3,Java 8 能连上吗?

只有 8u261 及以上(默认启用 TLS 1.3)可以。更早的 8u 版本即使手动开启也未必含完整实现,建议直接升级 JDK,或让服务端保留 TLS 1.2 作为过渡。

Q3:客户端支持 TLS 1.3、服务端只有 TLS 1.2,能握手成功吗?

能。TLS 版本协商向下兼容,客户端会同时提议 1.3 与 1.2,服务端选择 1.2。只有双方集合完全无交集时才会失败。

Q4:升级 JDK 后错误依旧,最可能是什么原因?

三个高发原因:进程实际用的不是新 JDK;jdk.tls.disabledAlgorithms 被人为加了 TLSv1.2;客户端代码或框架把协议写死成单一版本。按第二节的 -XshowSettings 与握手日志逐项排除即可。

Q5:能不能直接把 TLSv1 / TLSv1.1 加回 java.security 应急?

技术上可以(从 jdk.tls.disabledAlgorithms 中移除对应项),但这会打开已被主流浏览器与 PCI DSS 淘汰的协议,属于饮鸩止渴。正确做法是服务端保留 TLSv1.2、客户端升级,并把 TLS 1.3 作为目标态。

Q6:如何在不改代码、不改配置的前提下快速判断是不是协议问题?

用 openssl 分别以 -tls1_2 和 -tls1_3 连服务端,再用同一台机器上的 Java 程序连一次。openssl 成功而 Java 失败,基本可以锁定是客户端协议被裁剪。

Q7:改了 java.security 需要重启吗?容器里为什么总是不生效?

需要重启 JVM,该文件只在启动时读取一次。容器里不生效,通常是改了宿主机的文件、或镜像层被覆盖。务必确认 java.home 指向的真实路径,并在 Dockerfile 中固化修改,避免每次发布被重置。

最后给一句结论:protocol_version 永远不是“Java 的 bug”,而是两端协议集合的交集为空。先用 openssl 和 -Djavax.net.debug 把双方能力测出来,再决定是升级客户端、放开服务端,还是两者同时调整。