国密 TLCP 实战：GmSSL / OCL / Nginx 版本选型与全部调试修改说明

本文面向发布到 CSDN汇总本人在 Windows WSL2 编译、Docker 部署、CentOS 生产环境跑通Nginx 国密 HTTPSTLCP时使用的源码版本、目录布局以及为调通而做的全部修改含配置、脚本、证书处理不含对 Nginx 核心 C 源码的 patch。参考博文基于 GmSSL 搭建 Nginx 国密反代流程可参考但部分写法如ssl_protocols GMTLS与当前 OCL/Nginx 行为不完全一致下文会说明。一、环境与目录布局环境说明开发机Windows 10/11 WSL2 Ubuntu 24.04生产机CentOS 7 系10.131.111.250Docker 运行源码根目录/mnt/d/codes/Windows 对应D:\codes\推荐三仓库并列/mnt/d/codes/ ├── GmSSL/ # 国密算法库 ├── OpenSSL-Compatibility-Layer/ # OpenSSL 兼容层OCL └── nginx/ # Nginx 1.25.3 源码 Docker 工程证书调试目录与仓库分离便于拷到生产机/mnt/d/nginx_gm/certs/ # 自建 CA 服务器 TLCP 证书 /opt/nginx/certs/ # 生产机挂载进容器 /opt/nginx/conf/nginx.conf # 生产机自定义主配置二、引用的三个项目及版本务必对齐2.1 版本总表项目仓库推荐 Tag / 版本用途GmSSLhttps://github.com/guanzhi/GmSSLv3.1.1OCL 依赖gmssl命令行生成证书OpenSSL-Compatibility-Layerhttps://github.com/GmSSL/OpenSSL-Compatibility-Layerv0.8.1提供libssl.so/libcrypto.so伪装 OpenSSL APINginxhttps://nginx.org 或本仓库release-1.25.31.25.3OCL README 明确测试过的版本运行环境版本WSL 编译Ubuntu24.04gcc13.3.0Docker 基础镜像Ubuntu24.04Docker 镜像标签nginx-gmssl:1.25.32.2 版本不对齐时的典型现象错配现象GmSSL 用masterNginx/OCL 用 v3.1.1 编译WSL 上gmssl tlcp_client报tls.c:2829:tls_init(): error见下文 §5.3Nginx 1.31 未在 OCL 列表中编译或握手阶段未知问题不建议生产首选用系统 OpenSSL 3.x 未被子替换nginx -V显示 SSL 但握手仍是国际算法gmssl与链接进 Nginx 的libgmssl不是同一次编译证书工具能生成运行时库行为不一致2.3 编译安装顺序固定① GmSSL (v3.1.1) → sudo make install → /usr/local/lib/libgmssl.so ② OCL (v0.8.1) → sudo make install → /usr/local/lib/libssl.so, libcrypto.so ③ Nginx (1.25.3) → ./configure make → objs/nginx安装 OCL 后必须确认默认头文件/库来自 OCL而不是系统 OpenSSLgrep-iOPENSSL /usr/local/include/openssl/opensslv.h ldd /usr/local/lib/libcrypto.so|grepgmssl三、各组件编译参数最终调通版3.1 GmSSL v3.1.1cd/mnt/d/codes/GmSSLgitfetch--tagsgitcheckout v3.1.1mkdirbuildcdbuild cmake..make-j$(nproc)sudomakeinstall# 命令行工具whichgmssl# 期望 /usr/local/bin/gmssl说明证书在/mnt/d/nginx_gm/certs用gmssl sm2keygen/certgen/reqgen/reqsign生成口令示例Ilovecn123签名私钥与加密私钥必须相同OCL 硬性要求。对 GmSSL 源码的修改无仅git checkout v3.1.1避免使用 master 做客户端测试。3.2 OpenSSL-Compatibility-Layer v0.8.1cd/mnt/d/codes/OpenSSL-Compatibility-Layergitfetch--tagsgitcheckout v0.8.1mkdirbuildcdbuild cmake..make-j$(nproc)sudomakeinstall安装结果头文件/usr/local/include/openssl/OCL 头文件库/usr/local/lib/libssl.so、libcrypto.so底层依赖libgmssl对 OCL 源码的修改生产调通路径无 patch。理解其行为即可不必改代码见 §5.1pem.c逻辑。社区可选 patch浏览器访问报错时OCL Issue #13 提到在 GmSSL 的src/tlcp.c的tlcp_do_accept中注释客户端扩展校验以兼容部分国密浏览器。本人生产调通未改此文件若奇安信/360 握手失败可再评估。3.3 Nginx 1.25.3第一次 configure踩坑缺 PCRE./configure\--prefix/usr/local/nginx\--with-http_ssl_module\--with-stream\--with-stream_ssl_module\--without-http_rewrite_moduleobjs/ngx_auto_config.h中无NGX_PCRE配置里写location ~* \.(js|css|...)$会报nginx: [emerg] using regex ... requires PCRE library最终 configure调通版sudoaptinstall-ylibpcre3-dev ./configure\--prefix/usr/local/nginx\--with-http_ssl_module\--with-stream\--with-stream_ssl_module\--with-pcre\--with-pcre-jitmake-j$(nproc)当前工程内记录的编译参数objs/ngx_auto_config.h#defineNGX_CONFIGURE --prefix/usr/local/nginx --with-http_ssl_module --with-stream --with-stream_ssl_module --without-http_rewrite_module --with-pcre --with-pcre-jit验证objs/nginx-V# 应含 openssl 相关信息且 ldd objs/nginx | grep -E ssl|crypto|gmssl对 Nginx 官方源码src/的修改无。国密能力完全来自链接 OCL 的 libssl不是 nginx 补丁模块。四、Docker 工程修改本仓库nginx/docker/采用「WSL 编好二进制 拷贝 .so → 镜像只打包」策略不在镜像内重编三件套。4.1docker/prepare.sh打包动态库将 sibling 目录编译产物拷入vendor/lib../GmSSL/build/bin/libgmssl.so* ../OpenSSL-Compatibility-Layer/build/libssl.so* ../OpenSSL-Compatibility-Layer/build/libcrypto.so*4.2Dockerfile要点基础镜像ubuntu:24.04安装运行时依赖libpcre3、zlib1g不在镜像里装开发包COPY objs/nginx→/usr/local/nginx/sbin/nginxENV LD_LIBRARY_PATH/usr/local/libEXPOSE 80 4443生产映射-p 443:443时由宿主机nginx.conf决定 listen4.3docker-entrypoint.sh修改重要修改前旧镜像逻辑导致容器秒退if[!-f/certs/tlcp_server_certs.pem]||[!-f/certs/tlcp_server_keys.pem];thenechoerror: TLCP certs required under /certs (see docker/README.md)exit1fi生产挂载为/etc/nginx/certs/文件名也可能是sign-fullchain.pem等与/certs/tlcp_server_*.pem不一致 →entrypoint 直接 exit 1。修改后当前文件#!/bin/shset-eNGINX/usr/local/nginx/sbin/nginx ldconfig2/dev/null||trueif[$1$NGINX]||[$(basename$12/dev/null)nginx];then$NGINX-tfiexec$仅做nginx -t不再硬编码证书路径。4.4docker/default.conf修改修改前ssl_certificate /certs/tlcp_server_certs.pem; ssl_certificate_key /certs/tlcp_server_keys.pem; ssl_password_file /certs/tlcp_server_password.txt;修改后ssl_certificate /etc/nginx/certs/tlcp_server_certs.pem; ssl_certificate_key /etc/nginx/certs/tlcp_server_keys.pem; ssl_password_file /etc/nginx/certs/tlcp_server_password.txt;与docker-compose.yml挂载./certs:/etc/nginx/certs:ro一致。4.5 生产docker run相对最初命令的修正dockerrun-d\--namenginx-gm\-p443:443\-v/opt/nginx/certs:/etc/nginx/certs:ro\-v/opt/nginx/conf/nginx.conf:/usr/local/nginx/conf/nginx.conf:ro\-v/opt/nginx/html:/etc/nginx/html:ro\-v/opt/nginx/logs:/usr/local/nginx/logs\nginx-gmssl:1.25.3最初写法问题--name nginx-gm重复命令非法或覆盖logs→/var/log/nginx:ro前缀应为/usr/local/nginx/logs且不能只读cache无关只读挂载与 nginx 无关易误导旧 entrypoint 旧镜像证书未放到/certs/tlcp_server_*.pem即退出五、生产nginx.conf与证书运维侧修改5.1 证书文件OCL 要求非 Nginx 官方格式服务器侧三个文件/opt/nginx/certs/文件内容顺序tlcp_server_certs.pem终端签名证→ 终端加密证→中间 CA不要根证tlcp_server_keys.pem签名加密私钥→加密加密私钥两段ENCRYPTED PRIVATE KEYpassword.txt一行口令无\r生成示例与 OCL README 一致catsigncert.pem enccert.pem cacert.pemtlcp_server_certs.pemcatsignkey.pem enckey.pemtlcp_server_keys.pemprintf%s\nIlovecn123password.txt证书处理上的“修改”非改 C 代码厂商未加密私钥BEGIN PRIVATE KEY→ 用gmssl pkcs8 -topk8加密后再合并。厂商分体 fullchainsign-fullchain.pemenc-fullchain.pem→ 改为 OCL 推荐的单证链 双钥文件。password.txt与密钥口令不一致曾用12345678而密钥为Ilovecn123→ 统一口令并cat -A检查无^M。5.2 生产server块最终server { listen 443 ssl; server_name 10.131.111.250; ssl_certificate /etc/nginx/certs/tlcp_server_certs.pem; ssl_certificate_key /etc/nginx/certs/tlcp_server_keys.pem; ssl_password_file /etc/nginx/certs/password.txt; ssl_ecdh_curve sm2p256v1; ssl_ciphers ECDHE-SM2-WITH-SMS4-SM3:ECDHE-SM2-WITH-SMS4-GCM-SM3; ssl_prefer_server_ciphers on; location / { root /etc/nginx/html; index index.html index.htm; } }相对 CSDN 参考文/初稿删除或禁止的项# 错误 — Nginx 配置解析不认 GMTLS ssl_protocols GMTLS TLSv1.2; # 错误 — OCL 双钥加密场景不要删 # ssl_password_file ...说明TLCP 由 GmSSL 在libssl内完成不需要也不能在ssl_protocols里写GMTLS。5.3 OCL 读私钥逻辑理解即可解释为何必须加密口令OCLsrc/pem.c中PEM_read_bio_PrivateKey核心逻辑v0.8.1 / main 同类// 必须有 password 回调if(!bio||!cb||!u){error_print();returnNULL;}cb(pass,sizeof(pass),0,u);// 同一 BIO 连续读两把 SM2 私钥sm2_private_key_info_decrypt_from_pem(pkey-signkey,pass,bio);sm2_private_key_info_decrypt_from_pem(pkey-kenckey,pass,bio);因此必须配置ssl_password_filetlcp_server_keys.pem必须是PKCS#8 加密格式BEGIN ENCRYPTED PRIVATE KEY两把钥同一口令。六、GmSSL 命令行版本问题WSL 调试6.1 现象gmssl tlcp_client-get/-host10.131.111.250-port443-cacertrootcacert.pem# /mnt/d/codes/GmSSL/src/tls.c:2829:tls_init():# tlcp_client: error此时服务器docker exec nginx-gm nginx -t已successfulnc443 通。6.2 原因WSL 中/usr/local/bin/gmssl若来自GmSSL mastertls_init()会检查key_exchange_modes ! 0而tlcp_client未设置 supported_groups / signature_algorithms导致客户端在握手前就失败。v3.1.1的tls_init无此检查且会正确设置conn-is_client ctx-is_client。6.3 处理版本切换非改 tls.ccd/mnt/d/codes/GmSSLgitcheckout v3.1.1rm-rfbuildmkdirbuildcdbuildcmake..make-j$(nproc)sudomakeinstall6.4 不要用这些方式判断服务是否存活工具结果原因curl https://IP:443PR_END_OF_FILE_ERROR国际 TLS vs TLCPopenssl pkey -in tlcp_server_keys.pemunable to load key系统 OpenSSL 不支持 SM2七、修改项汇总表便于 CSDN 读者对照序号对象是否改上游 C 源码修改内容1GmSSL否固定tag v3.1.1不用 master 跑tlcp_client2OCL否可选 tlcp.c 见 Issue #13固定tag v0.8.1理解pem.c双钥解密3Nginx否configure 增加--with-pcre --with-pcre-jit4docker-entrypoint.sh项目脚本去掉/certs/tlcp_server_*.pem强校验仅nginx -t5docker/default.conf项目配置证书路径/certs→/etc/nginx/certs6生产nginx.conf运维配置listen 443删GMTLSOCL 三件套路径7证书文件运维合并证链/双钥加密私钥password.txt去 CRLF8docker run运维日志可写、去掉错误 volume、更新镜像八、验证通过标准本环境# 1. 编译链ldd /usr/local/nginx/sbin/nginx|grepgmssl objs/nginx-V# 2. 容器dockerexecnginx-gm /usr/local/nginx/sbin/nginx-t# configuration file ... test is successful# 3. 监听镜像可能无 ssdockerexecnginx-gmsh-ccat /proc/net/tcp|grep01BB# 443# 4. 客户端GmSSL v3.1.1gmssl tlcp_client-get/-host10.131.111.250-port443-cacertrootcacert.pem# 5. 浏览器# 国密浏览器 导入 rootcacert.pem → https://10.131.111.250/九、发布 CSDN 时的建议标签Nginx国密GmSSLTLCPOpenSSL-Compatibility-LayerSM2DockerHTTPS十、参考链接GmSSL/OpenSSL-Compatibility-Layer READMEguanzhi/GmSSLTagv3.1.1GmSSL Issue #1156 - invalid value GMTLSOCL Issue #13 - 浏览器访问国密 nginx本人部署踩坑合集同目录nginx-gmssl-部署总结.md版权声明版本号与修改记录基于 2026 年 5 月实际调试环境整理若上游 tag 更新请以各项目 Release 说明为准并重新做nginx -t与tlcp_client回归。