文章目录00 导读1. 先说结论你要完成的是一条链不是一行代码2. 接入前必须向对方确认的 12 个问题2.1 对方到底支持哪种“国密 SSL”2.2 服务端地址和接口2.3 服务端证书和 CA 链2.4 是否需要客户端证书3. 本工程已经帮你做了什么3.1 用 Maven 固定关键依赖3.2 提供配置入口3.3 提供两条调用路径4. 学习路线先跑通再理解再收敛第一步确认概念第二步读工程地图第三步本地构建第四步部署联调页面第五步把参数固化到业务配置第六步按排障手册定位异常5. 你最终应该交付什么6. 这一篇的重点回顾00 导读很多人第一次听到“接入国密 SSL”第一反应是是不是把 HTTPS URL 换一下、把证书放进项目就行实际项目里通常没这么简单。原因有三个“国密 SSL”不是一个非常精确的技术名词。对方可能指 TLCP/GMSSL/NTLS也可能指 TLS 1.3 国密套件也可能只是说“证书用 SM2”。Java 标准 JDK 默认不支持 TLCP也不认识很多国密证书/算法场景需要额外的安全 Provider。即使底层 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”请直接问你们服务端协议是TLCP / GMSSL / NTLS吗还是TLS 1.3 RFC 8998 国密套件URL 是否仍然写成https://host:port/path服务端是否同时开放普通 TLS 端口和 TLCP 端口对本工程来说答案是按 TLCP v1.1 接入。配置里也能看到gm:tlcp:tls:protocol:TLCPv1.1enabled-protocols:-TLCPv1.12.2 服务端地址和接口至少要有字段示例本工程默认值schemehttpshttpshostxxxxxxxportxxxxxxxxxpath/xxx/v1/file/upload/xxx/v1/file/uploadHTTP methodPOSTPOSTbody 类型multipartmultipart文件字段名filefile特殊请求头Content-MetaJSON 字符串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、JKSKeyStore 密码和私钥密码是否相同服务端是否只接受TLCP_ECDHE_*这类套件本工程默认是不发送客户端证书client-key-store:path:type:PKCS12password:key-password:如果对方要求双向认证要改成类似gm:tlcp:tls:client-key-store:path:file:/secure/client.p12type:PKCS12password:changeitkey-password:changeit3. 本工程已经帮你做了什么3.1 用 Maven 固定关键依赖pom.xml中关键版本java.version1.8/java.versionforest.version1.8.0/forest.versiontencent-kona.version1.0.20/tencent-kona.version依赖里包括kona-cryptoSM2/SM3/SM4 等算法kona-pkix国密证书解析、证书链验证、KeyStore 支持kona-sslTLCP / 国密 TLS 相关 SSL 能力forest-spring-boot-starterHTTP 请求构造okhttp 3.14.9Forest 底层传输。3.2 提供配置入口所有关键参数集中在src/main/resources/application.ymlgm: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.cer3.3 提供两条调用路径第一条是业务代码路径StringresponseuploadClient.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、证书和 CA02 标准背景国际 TLS、RFC 8998 与中国 TLCP03 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 接入不只是“代码合了”。应该至少交付一份配置文件目标地址、证书路径、协议、密码套件、超时时间。一份证书材料说明哪些是 CA哪些是客户端证书过期时间是什么。一份联调记录成功请求的时间、目标、HTTP 状态码、响应体摘要。一份握手诊断协议、密码套件、Provider、证书摘要、hostname 校验结果。一份排障表出现常见错误时找谁、改哪里、看什么日志。一份上线检查表生产环境是否启用 hostname verification、证书是否外置、密码是否不进 Git。这也是本系列最后一篇 10 上线检查表 要解决的问题。6. 这一篇的重点回顾“国密 SSL”先要问清楚是 TLCP、TLS 1.3 国密套件还是普通 TLS SM2 证书。接入不是只放证书而是协议、证书、Provider、SSLContext、HTTP 客户端、业务请求全链路对齐。本工程已经给出一条可运行的 TLCP 客户端链路配置 → Kona Provider → TLCP SSLContext → OkHttp 兼容层 → Forest multipart 上传 → Web 诊断页面。新手不要跳过诊断页面它能让你先确认问题在握手层还是业务层。
Web安全 - 国密 SSL 接入到底要做什么
文章目录00 导读1. 先说结论你要完成的是一条链不是一行代码2. 接入前必须向对方确认的 12 个问题2.1 对方到底支持哪种“国密 SSL”2.2 服务端地址和接口2.3 服务端证书和 CA 链2.4 是否需要客户端证书3. 本工程已经帮你做了什么3.1 用 Maven 固定关键依赖3.2 提供配置入口3.3 提供两条调用路径4. 学习路线先跑通再理解再收敛第一步确认概念第二步读工程地图第三步本地构建第四步部署联调页面第五步把参数固化到业务配置第六步按排障手册定位异常5. 你最终应该交付什么6. 这一篇的重点回顾00 导读很多人第一次听到“接入国密 SSL”第一反应是是不是把 HTTPS URL 换一下、把证书放进项目就行实际项目里通常没这么简单。原因有三个“国密 SSL”不是一个非常精确的技术名词。对方可能指 TLCP/GMSSL/NTLS也可能指 TLS 1.3 国密套件也可能只是说“证书用 SM2”。Java 标准 JDK 默认不支持 TLCP也不认识很多国密证书/算法场景需要额外的安全 Provider。即使底层 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”请直接问你们服务端协议是TLCP / GMSSL / NTLS吗还是TLS 1.3 RFC 8998 国密套件URL 是否仍然写成https://host:port/path服务端是否同时开放普通 TLS 端口和 TLCP 端口对本工程来说答案是按 TLCP v1.1 接入。配置里也能看到gm:tlcp:tls:protocol:TLCPv1.1enabled-protocols:-TLCPv1.12.2 服务端地址和接口至少要有字段示例本工程默认值schemehttpshttpshostxxxxxxxportxxxxxxxxxpath/xxx/v1/file/upload/xxx/v1/file/uploadHTTP methodPOSTPOSTbody 类型multipartmultipart文件字段名filefile特殊请求头Content-MetaJSON 字符串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、JKSKeyStore 密码和私钥密码是否相同服务端是否只接受TLCP_ECDHE_*这类套件本工程默认是不发送客户端证书client-key-store:path:type:PKCS12password:key-password:如果对方要求双向认证要改成类似gm:tlcp:tls:client-key-store:path:file:/secure/client.p12type:PKCS12password:changeitkey-password:changeit3. 本工程已经帮你做了什么3.1 用 Maven 固定关键依赖pom.xml中关键版本java.version1.8/java.versionforest.version1.8.0/forest.versiontencent-kona.version1.0.20/tencent-kona.version依赖里包括kona-cryptoSM2/SM3/SM4 等算法kona-pkix国密证书解析、证书链验证、KeyStore 支持kona-sslTLCP / 国密 TLS 相关 SSL 能力forest-spring-boot-starterHTTP 请求构造okhttp 3.14.9Forest 底层传输。3.2 提供配置入口所有关键参数集中在src/main/resources/application.ymlgm: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.cer3.3 提供两条调用路径第一条是业务代码路径StringresponseuploadClient.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、证书和 CA02 标准背景国际 TLS、RFC 8998 与中国 TLCP03 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 接入不只是“代码合了”。应该至少交付一份配置文件目标地址、证书路径、协议、密码套件、超时时间。一份证书材料说明哪些是 CA哪些是客户端证书过期时间是什么。一份联调记录成功请求的时间、目标、HTTP 状态码、响应体摘要。一份握手诊断协议、密码套件、Provider、证书摘要、hostname 校验结果。一份排障表出现常见错误时找谁、改哪里、看什么日志。一份上线检查表生产环境是否启用 hostname verification、证书是否外置、密码是否不进 Git。这也是本系列最后一篇 10 上线检查表 要解决的问题。6. 这一篇的重点回顾“国密 SSL”先要问清楚是 TLCP、TLS 1.3 国密套件还是普通 TLS SM2 证书。接入不是只放证书而是协议、证书、Provider、SSLContext、HTTP 客户端、业务请求全链路对齐。本工程已经给出一条可运行的 TLCP 客户端链路配置 → Kona Provider → TLCP SSLContext → OkHttp 兼容层 → Forest multipart 上传 → Web 诊断页面。新手不要跳过诊断页面它能让你先确认问题在握手层还是业务层。
