Web安全 - 国密 SSL 接入到底要做什么

00 导读

很多人第一次听到“接入国密 SSL”，第一反应是：是不是把 HTTPS URL 换一下、把证书放进项目就行？实际项目里通常没这么简单。

原因有三个：

1. “国密 SSL”不是一个非常精确的技术名词。对方可能指 TLCP/GMSSL/NTLS，也可能指 TLS 1.3 + 国密套件，也可能只是说“证书用 SM2”。
2. Java 标准 JDK 默认不支持 TLCP，也不认识很多国密证书/算法场景，需要额外的安全 Provider。
3. 即使底层 TLCP 能握手，常见 HTTP 客户端库也可能在“协议名、密码套件名、证书校验、连接规格”上卡住。

本工程就是为了解决一个具体场景：Java/Spring Boot 客户端通过 TLCP v1.1 调远端文件上传接口。

1. 先说结论：你要完成的是一条链，不是一行代码

一条真正可用的 TLCP 客户端链路至少包括：

确认协议类型 ↓ 拿到服务端地址、端口、接口路径 ↓ 拿到CA根证书/中间CA证书 ↓ 确认是否需要客户端证书（双向认证） ↓ 确认TLCP版本与密码套件 ↓ 在Java里注册国密Provider↓ 把CA证书加载进TrustStore↓ 可选：把客户端私钥证书加载进KeyStore↓ 创建TLCPSSLContext↓ 把SSLContext接到HTTP客户端 ↓ 发业务请求 ↓ 根据握手日志、证书摘要、响应体定位问题

你可以把它想成“修一条高速公路”：

• 证书是通行证；
• CA 是发证机关；
• TrustStore 是“我信任哪些发证机关”的名单；
• KeyStore 是“我自己的身份证和私钥”；
• TLCP/密码套件是“双方说同一种加密语言”；
• HTTP 客户端只是最后开车上路的工具。

如果前面的任意一个环节错了，最后看到的往往只是一个很泛的错误：handshake_failure、certificate verify failed、no suitable signature algorithm、Unexpected TLS version: TLCPv1.1。

2. 接入前必须向对方确认的 12 个问题

在你动代码前，先拿到这些信息。没拿全也能试，但排错成本会很高。

2.1 对方到底支持哪种“国密 SSL”

请直接问：

1. 你们服务端协议是TLCP / GMSSL / NTLS吗？
2. 还是TLS 1.3 + RFC 8998 国密套件？
3. URL 是否仍然写成https://host:port/path？
4. 服务端是否同时开放普通 TLS 端口和 TLCP 端口？

对本工程来说，答案是：按 TLCP v1.1 接入。配置里也能看到：

gm:tlcp:tls:protocol:TLCPv1.1enabled-protocols:-TLCPv1.1

2.2 服务端地址和接口

至少要有：

2.3 服务端证书和 CA 链

你要问对方：

• 给我的是服务端证书，还是 CA 证书？
• 有没有根 CA？有没有中间 CA？顺序是什么？
• 证书是 DER.cer，还是 PEM.crt/.pem？
• 服务端证书的 SAN/CN 是否包含我访问的 host 或 IP？
• 证书是否快过期？

本工程默认信任两张 CA 证书：

classpath:certs/ROOTCA.cer classpath:certs/XXXXSM2CA.cer

注意：客户端通常不应该把服务端叶子证书硬塞成唯一信任根。更常见的做法是信任签发服务端证书的根 CA / 中间 CA。

2.4 是否需要客户端证书

这决定你是否要配置client-key-store。

问法：

• 服务端是否要求双向认证？
• 如果要求，客户端证书是否也是双证书？
• 客户端私钥和证书给什么格式？PEM、P12、JKS？
• KeyStore 密码和私钥密码是否相同？
• 服务端是否只接受TLCP_ECDHE_*这类套件？

本工程默认是不发送客户端证书：

client-key-store:path:type:PKCS12password:key-password:

如果对方要求双向认证，要改成类似：

gm:tlcp:tls:client-key-store:path:file:/secure/client.p12type:PKCS12password:changeitkey-password:changeit

3. 本工程已经帮你做了什么

3.1 用 Maven 固定关键依赖

pom.xml中关键版本：

<java.version>1.8</java.version><forest.version>1.8.0</forest.version><tencent-kona.version>1.0.20</tencent-kona.version>

依赖里包括：

• kona-crypto：SM2/SM3/SM4 等算法；
• kona-pkix：国密证书解析、证书链验证、KeyStore 支持；
• kona-ssl：TLCP / 国密 TLS 相关 SSL 能力；
• forest-spring-boot-starter：HTTP 请求构造；
• okhttp 3.14.9：Forest 底层传输。

3.2 提供配置入口

所有关键参数集中在src/main/resources/application.yml：

gm:tlcp:scheme:httpshost:192.168.8.101port:12345upload-path:/xxxx/v1/file/uploadtls:protocol:TLCPv1.1enabled-protocols:-TLCPv1.1enabled-cipher-suites:-TLCP_ECC_SM4_GCM_SM3-TLCP_ECC_SM4_CBC_SM3client-signature-schemes:-sm2sig_sm3hostname-verification-enabled:falsetrust-certificates:-classpath:certs/ROOTCA.cer-classpath:certs/xxxxSM2CA.cer

3.3 提供两条调用路径

第一条是业务代码路径：

Stringresponse=uploadClient.upload(newFile("/root/a.txt"),newContentMeta("temp.txt",1140L,"/root/testfile","user123"));

第二条是 Web 联调路径：

GET / GET /api/tlcp/defaults POST /api/tlcp/upload

你可以先用 Web 页面把握手调通，再把同样的参数固化到业务配置里。

4. 学习路线：先跑通，再理解，再收敛

建议按这个顺序做：

第一步：确认概念

读：

• 01 小白基础：SSL、TLS、HTTPS、证书和 CA
• 02 标准背景：国际 TLS、RFC 8998 与中国 TLCP
• 03 TLCP 握手：双证书、密码套件与常见术语

目标：看到TLCP_ECC_SM4_GCM_SM3、sm2sig_sm3、TrustStore、KeyStore不再懵。

第二步：读工程地图

读：

• 04 工程全景：本项目每个类负责什么

目标：知道出问题时该看哪个类、哪个配置、哪个返回字段。

第三步：本地构建

执行：

mvntestmvn package

目标：确认依赖能下载，Kona Provider 能注册，证书能被读取。

第四步：部署联调页面

执行：

java-jartarget/gm-ssl-client-0.0.1-SNAPSHOT.jar

浏览器打开：

http://<服务器IP>:9876/

目标：用页面发一次请求，拿到tlcp和tlcpTrace诊断信息。

第五步：把参数固化到业务配置

读：

• 06 手把手发起请求：Web 页面、curl 与业务代码
• 08 进阶配置：双向认证、密码套件和 hostname 校验

目标：从“页面能跑”变成“服务启动后业务代码能跑”。

第六步：按排障手册定位异常

读：

• 09 排障手册：从错误日志定位 TLCP 问题

目标：不要靠猜，按现象分层定位。

5. 你最终应该交付什么

一次合格的国密 SSL/TLCP 接入，不只是“代码合了”。应该至少交付：

1. 一份配置文件：目标地址、证书路径、协议、密码套件、超时时间。
2. 一份证书材料说明：哪些是 CA，哪些是客户端证书，过期时间是什么。
3. 一份联调记录：成功请求的时间、目标、HTTP 状态码、响应体摘要。
4. 一份握手诊断：协议、密码套件、Provider、证书摘要、hostname 校验结果。
5. 一份排障表：出现常见错误时找谁、改哪里、看什么日志。
6. 一份上线检查表：生产环境是否启用 hostname verification、证书是否外置、密码是否不进 Git。

这也是本系列最后一篇 10 上线检查表 要解决的问题。

6. 这一篇的重点回顾

• “国密 SSL”先要问清楚是 TLCP、TLS 1.3 国密套件，还是普通 TLS + SM2 证书。
• 接入不是只放证书，而是协议、证书、Provider、SSLContext、HTTP 客户端、业务请求全链路对齐。
• 本工程已经给出一条可运行的 TLCP 客户端链路：配置 → Kona Provider → TLCP SSLContext → OkHttp 兼容层 → Forest multipart 上传 → Web 诊断页面。
• 新手不要跳过诊断页面，它能让你先确认问题在握手层还是业务层。