安全攻防 - 04 GMSSL 工程介绍

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

前面三篇讲概念。这一篇开始回到本工程。目标是让你打开代码时不迷路：哪个类负责配置，哪个类负责证书，哪个类负责 Provider，哪个类负责 OkHttp，哪个类负责发请求。

1. 工程一句话说明

本工程是一个：

Spring Boot 2.7.18 + Java 8 + Forest 1.8.0 + OkHttp 3.14.9 + Tencent Kona 1.0.20

组成的 TLCP 客户端示例。

它做两件事：

1. 提供一个业务上传客户端DdFileUploadClient；
2. 提供一个 Web 联调页面，部署后从浏览器直接测试 TLCP 文件上传。

默认远端：

https://IP：port/context-path/v1/file/upload

默认本地调试页面：

http://<部署机>:9876/

2. 目录结构

核心文件：

src/main/java/com/artisan/gmssl/├──GmSslClientApplication.java ├── config/│ └──GmTlcpProperties.java ├── tlcp/│ ├──ConfigurableHostnameVerifier.java │ ├──KonaProviderInitializer.java │ ├──TlcpCertificateDetails.java │ ├──TlcpHandshakeRecorder.java │ ├──TlcpOkHttpClientFactory.java │ ├──TlcpProtocolMaskingSslSession.java │ ├──TlcpProtocolMaskingSslSocket.java │ ├──TlcpProtocolMaskingSslSocketFactory.java │ └──TlcpSslContextFactory.java └── upload/├──ContentMeta.java ├──DdFileUploadClient.java ├──InteractiveUploadRequest.java ├──InteractiveUploadService.java ├──StartupUploadRunner.java ├──UploadClientProperties.java └──UploadDebugController.java

资源文件：

src/main/resources/├── application.yml ├── certs/│ ├──ROOTCA.cer │ └──MiddleSM2CA.cer └──static/└── index.html

测试文件：

src/test/java/com/artisan/gmssl/├── tlcp/└── upload/

3. 启动入口

GmSslClientApplication.java是标准 Spring Boot 启动类：

@SpringBootApplication@EnableConfigurationProperties({GmTlcpProperties.class,UploadClientProperties.class})publicclassGmSslClientApplication{publicstaticvoidmain(String[]args){SpringApplication.run(GmSslClientApplication.class,args);}}

重点是启用了两个配置类：

4. 配置层：GmTlcpProperties

这个类对应application.yml的：

gm:tlcp:scheme:httpshost:your-ipport:your-portupload-path:/context-path/v1/file/upload

它提供两个方便方法：

publicStringbaseUrl(){returnscheme+"://"+host+":"+port;}publicStringuploadUrl(){...returnbaseUrl()+path;}

也就是说业务代码不用到处拼 URL。

4.1 TLS 子配置

GmTlcpProperties.Tls里放 TLCP 相关参数：

privateStringprotocol="TLCPv1.1";privateList<String>enabledProtocols=["TLCPv1.1"];privateList<String>enabledCipherSuites=["TLCP_ECC_SM4_GCM_SM3","TLCP_ECC_SM4_CBC_SM3"];privateList<String>clientSignatureSchemes=["sm2sig_sm3"];privateList<String>trustCertificates=["classpath:certs/ROOTCA.cer","classpath:certs/MiddleSM2CA.cer"];privatebooleanhostnameVerificationEnabled=false;

这就是你接入不同服务端时最常改的地方。

4.2 客户端 KeyStore 子配置

privatefinalKeyStoreConfigclientKeyStore=newKeyStoreConfig();

默认没有 path，也就不启用客户端证书。

一旦你填了：

client-key-store:path:file:/secure/client.p12

TlcpSslContextFactory就会把它加载成 KeyManager。

5. Provider 层：KonaProviderInitializer

这个类负责两件事。

第一，设置 Kona 客户端签名算法：

com.tencent.kona.ssl.client.signatureSchemes=sm2sig_sm3

第二，注册三个 Provider：

KonaCryptoProvider.instance()KonaPKIXProvider.instance()KonaSSLProvider.instance()

它的设计细节：

• @PostConstruct启动时执行；
• initialize()是幂等的，重复调用不会重复注册；
• TlcpSslContextFactory每次构造 SSLContext 前也会调用一次，防止单测或 Bean 顺序导致 Provider 没注册。

新手理解：没有这个类，后面SSLContext.getInstance("TLCPv1.1", "KonaSSL")很可能找不到 Provider。

6. SSLContext 层：TlcpSslContextFactory

这是 TLCP 接入核心类。

它做四件事：

1.读取信任证书2.生成TrustManager3.可选读取客户端KeyStore并生成KeyManager4.创建SSLContext("TLCPv1.1","KonaSSL")

6.1 证书路径解析

支持多种路径：

classpath:certs/ROOTCA.cer file:/secure/ROOTCA.cer/absolute/path/ROOTCA.cer relative/path/ROOTCA.cer

实现靠 Spring 的ResourceLoader，找不到时再回退到FileSystemResource。

6.2 TrustStore 构造

核心逻辑：

KeyStoretrustStore=KeyStore.getInstance("JKS","KonaPKIX");CertificateFactorycf=CertificateFactory.getInstance("X.509","KonaPKIX");TrustManagerFactorytmf=TrustManagerFactory.getInstance("PKIX","KonaSSL");

每个 Provider 都有意义：

6.3 SSLContext 构造

最终：

SSLContextsslContext=SSLContext.getInstance(contextProtocol,"KonaSSL");sslContext.init(keyManagers,trustManagers,newSecureRandom());

如果只是普通 HTTPS，你可能会写TLS。这里必须是TLCPv1.1+KonaSSL。

7. Hostname 层：ConfigurableHostnameVerifier

这个类很小：

if(!properties.getTls().isHostnameVerificationEnabled()){returntrue;}returndelegate.verify(hostname,session);

它解决的是联调环境问题：很多内网证书没有 IP SAN，直接启用 hostname verification 会失败。

但你要记住：

• 关闭 hostname verification 不等于关闭证书链校验；
• 生产环境更推荐让证书 SAN 正确，然后开启它。

8. OkHttp 层：TlcpOkHttpClientFactory

普通 TLCP SSLContext 已经能握手，但 OkHttp 3.x 还会卡两道关。

8.1 关卡 1：ConnectionSpec

OkHttp 默认MODERN_TLS不认识TLCPv1.1和TLCP_ECC_SM4_*。

本工程手动构造：

ConnectionSpectlcpSpec=newConnectionSpec.Builder(ConnectionSpec.MODERN_TLS).tlsVersions(enabledProtocols.toArray(newString[0])).cipherSuites(enabledCipherSuites.toArray(newString[0])).build();

然后：

.connectionSpecs(Arrays.asList(tlcpSpec,ConnectionSpec.CLEARTEXT))

8.2 关卡 2：握手后协议名解析

OkHttp 3.x 握手完成后会读取：

session.getProtocol()

如果返回TLCPv1.1，它的枚举不认识，可能抛：

Unexpected TLS version: TLCPv1.1

本工程用三件套解决：

TlcpProtocolMaskingSslSocketFactory TlcpProtocolMaskingSslSocket TlcpProtocolMaskingSslSession

只把给 OkHttp 看的SSLSession.getProtocol()改成TLSv1.2，底层真实 TLCP 握手字节流不变。

这是本项目最关键的兼容设计之一。

9. 诊断层：TlcpHandshakeRecorder

联调页面需要告诉你发生了什么，而不是只给一个异常。

TlcpHandshakeRecorder记录：

它只用于诊断路径，也就是InteractiveUploadService。

10. 上传层：DdFileUploadClient

这是业务代码真正可以注入使用的服务。

调用方式：

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

它内部：

校验文件和 Content-Meta ↓ 构造 TLCP OkHttpClient ↓ ForestConfiguration.post(properties.uploadUrl()) ↓ backendClient(okHttpClient) ↓ contentTypeMultipartFormData() ↓ addHeader("Content-Meta", contentMetaJson) ↓ addFile("file", file) ↓ executeAsString()

重点：它没有走 Forest 默认 SSL 管道，而是通过backendClient(okHttpClient)注入自定义 OkHttpClient。

这是绕过 OkHttp/Forest 默认 TLS 假设的关键。

11. Web 联调层

11.1 Controller

UploadDebugController提供：

GET / → static/index.html GET /api/tlcp/defaults → 返回默认表单参数 POST /api/tlcp/upload → 接收 multipart 文件并转发

11.2 Request DTO

InteractiveUploadRequest做三类事：

1. 从默认配置生成表单默认值；
2. 把逗号/换行分隔的协议、密码套件、证书路径拆成 List；
3. 把表单参数转换成临时GmTlcpProperties.Tls。

这让你可以在页面上临时改证书路径、密码套件、目标地址，而不需要改 jar 里的配置。

11.3 Service

InteractiveUploadService是 Web 联调核心：

应用默认值 ↓ 校验请求 ↓ 解析额外请求头 ↓ 构造临时TLS配置 ↓ 构造SSLContext/TrustManager/OkHttpClient↓ 把上传文件保存为临时文件 ↓Forest发 multipart 请求 ↓ 返回 request/tlcp/response/error/tlcpTrace

它返回的是一个结构化 JSON。排障时优先看这个 JSON，而不是只看控制台异常。

12. 启动上传层：StartupUploadRunner

默认不会启动就上传：

gm:upload:run-on-startup:false

这是安全设计，避免你本地mvn test或启动服务时自动请求内网远端。

如果确实要启动时发一次：

mvn spring-boot:run\-Dspring-boot.run.arguments="--gm.upload.run-on-startup=true --gm.upload.file=/root/a.txt"

13. 一张完整调用图

浏览器 index.html ↓POST/api/tlcp/uploadUploadDebugController↓InteractiveUploadService├─InteractiveUploadRequest.applyDefaults()├─TlcpSslContextFactory.buildSslContext()│ ├─KonaProviderInitializer.initialize()│ ├─buildTrustManagers()│ └─buildKeyManagers()├─TlcpHandshakeRecorder.socketFactory()├─TlcpOkHttpClientFactory.build()│ └─TlcpProtocolMaskingSslSocketFactory└─ForestRequest.backendClient(okHttpClient).executeAsResponse()↓ 远端TLCP服务

业务代码路径类似，只是从DdFileUploadClient开始，没有诊断 recorder。

14. 本篇小结

• 配置集中在GmTlcpProperties和application.yml。
• Provider 注册由KonaProviderInitializer负责。
• 证书加载、TrustManager、KeyManager、SSLContext 由TlcpSslContextFactory负责。
• OkHttp 兼容由TlcpOkHttpClientFactory和TlcpProtocolMaskingSsl*负责。
• 业务上传走DdFileUploadClient。
• Web 联调走UploadDebugController+InteractiveUploadService+index.html。
• 出问题时按层找，不要所有问题都归咎于证书。

下一篇开始手把手准备证书、配置和启动。