1. 项目概述为什么要在Nginx上折腾国密证书最近在给一个对数据安全有特殊要求的项目做技术选型客户明确要求通信链路必须支持国密算法。这让我不得不把目光从熟悉的RSA/ECC证书转向了国密SSL通常指SM2椭圆曲线公钥算法和SM3/SM4杂凑/分组密码算法证书。简单来说国密证书就是采用我国自主研发的密码算法标准生成的数字证书其核心是SM2算法对标国际上的ECC算法。在Nginx这类主流Web服务器上启用它意味着你的HTTPS服务从“国际标准”切换到了“国密标准”这对于满足国内某些行业的合规性要求如金融、政务、央企至关重要。你可能听过gmssl这个工具它是OpenSSL的一个分支专门集成了国密算法套件。所以为Nginx配置国密证书本质上就是让Nginx在编译或运行时能够调用支持国密算法的密码库如GmSSL、Tongsuo来处理SSL/TLS握手。这个过程听起来只是换个证书但实操中会遇到不少坑比如编译依赖、证书格式、Nginx配置参数等都和配置普通证书有差异。如果你正在为合规性发愁或者单纯想了解国密生态的落地那么这篇从一线踩坑经验总结出来的指南应该能帮你省下不少折腾的时间。2. 核心需求解析国密证书与GmSSL的定位在动手之前我们得先理清几个核心概念这决定了后续的技术路线。2.1 国密算法与国密证书国密算法是一套完整的密码体系在SSL/TLS场景下我们主要关注SM2 用于非对称加密和签名替代RSA和ECC。SM3 用于生成消息摘要哈希替代SHA-256等。SM4 用于对称加密替代AES。一张国密证书其公钥是基于SM2算法生成的。证书本身的标准格式通常是X.509但签名算法和公钥算法标识换成了国密对应的OID。这意味着传统的OpenSSL命令如openssl x509 -in cert.pem -text虽然能查看证书内容但可能无法正确识别或验证其SM2签名需要专门的工具或支持国密的库。2.2 GmSSL与Tongsuo国密OpenSSL实现的选择GmSSL是早期广泛使用的国密OpenSSL分支。但近年来其维护活跃度有所下降。另一个更活跃、由国内大厂维护的项目是Tongsuo原BabaSSL它同样完整支持国密算法并且与OpenSSL API兼容性更好社区支持也更积极。对于新项目我个人更倾向于推荐使用Tongsuo。本文将以Tongsuo为例进行说明但其原理和步骤与GmSSL高度相似。2.3 Nginx的国密支持模式Nginx本身不原生支持国密算法。要让Nginx支持国密HTTPS有两种主流方式动态模块 寻找或编译一个支持国密的SSL动态模块如ngx_http_gm_ssl_module在Nginx配置中加载。这种方式相对简单但模块的可用性和稳定性依赖第三方。静态编译 将支持国密的密码库如Tongsuo在编译Nginx时直接链接进去。这种方式生成的是一个“自带国密能力”的Nginx二进制文件部署更简单性能也更直接。我们通常推荐这种方式一劳永逸。我们的目标很明确编译一个内置了Tongsuo国密支持的Nginx并成功配置启用国密双证书可选或纯国密证书的单向/双向认证。3. 环境准备与依赖梳理工欲善其事必先利其器。我们先准备好编译环境和所需的源代码。3.1 系统环境与基础工具我是在一台干净的CentOS 7.9 x86_64虚拟机上操作的但步骤在Ubuntu 20.04/22.04上同样适用只需调整包管理命令yum-apt。# 安装编译工具和基础依赖 sudo yum groupinstall -y Development Tools sudo yum install -y pcre-devel zlib-devel wget git perl perl-devel3.2 获取源代码我们需要下载Nginx源码和Tongsuo源码。# 创建一个工作目录 mkdir -p ~/build/nginx_gm cd ~/build/nginx_gm # 下载Nginx稳定版源码 (以nginx-1.24.0为例) wget http://nginx.org/download/nginx-1.24.0.tar.gz tar -zxvf nginx-1.24.0.tar.gz # 下载Tongsuo源码 (以Tongsuo 8.3为例) git clone https://github.com/Tongsuo-Project/Tongsuo.git --depth 1 cd Tongsuo # 如果需要特定版本可以checkout tag例如 # git checkout 8.3.0注意 务必确认Tongsuo的版本与Nginx的兼容性。通常Tongsuo的发布说明或Wiki会注明其测试通过的Nginx版本。选择过新或过旧的组合可能导致编译失败或运行时错误。3.3 编译与安装TongsuoTongsuo需要先被编译和安装到系统目录如/usr/local/tongsuo这样Nginx编译时才能找到它。# 在Tongsuo源码目录中 ./config --prefix/usr/local/tongsuo --openssldir/usr/local/tongsuo/ssl enable-ntls make -j$(nproc) sudo make install这里有几个关键点--prefix 指定安装路径方便管理。enable-ntls这是一个关键选项。NTLSNational TLS是国密SSL的一种实现规范尤其对于需要同时支持国密和国际标准算法的双证书场景很重要。即使你暂时只用国密单证书也建议开启此选项以备后用。-j$(nproc) 使用所有CPU核心并行编译加快速度。编译安装完成后可以验证一下/usr/local/tongsuo/bin/openssl version如果输出包含“Tongsuo”字样和版本号说明安装成功。同时系统默认的openssl命令通常在/usr/bin/openssl仍然是原版两者互不干扰。4. 编译支持国密的Nginx现在进入核心环节编译Nginx并告诉它使用我们刚安装的Tongsuo。4.1 配置Nginx编译参数进入Nginx源码目录执行configure脚本。最关键的是--with-openssl参数它必须指向Tongsuo的源码目录不是安装目录。cd ~/build/nginx_gm/nginx-1.24.0 ./configure \ --prefix/usr/local/nginx_gm \ --with-http_ssl_module \ --with-openssl../Tongsuo \ --with-openssl-opt--prefix/usr/local/tongsuo enable-ntls \ --with-http_v2_module \ --with-http_stub_status_module \ --with-stream \ --with-stream_ssl_module参数解读--with-openssl../Tongsuo 这是最重要的参数告诉Nginx使用指定路径下的SSL库源码进行编译链接。--with-openssl-opt... 传递给TongsuoOpenSSL的配置选项这里我们再次申明安装前缀和启用NTLS。--with-http_ssl_module 启用HTTP SSL模块这是HTTPS的基础。其他模块http_v2,stub_status,stream_ssl根据你的实际需要添加。4.2 执行编译与安装配置完成后执行编译和安装。make -j$(nproc) sudo make install如果一切顺利一个支持国密的Nginx就被安装到了/usr/local/nginx_gm目录下。4.3 验证编译结果安装后首先验证Nginx二进制文件链接的SSL库是否正确/usr/local/nginx_gm/sbin/nginx -V在输出的巨长信息中你需要重点关注两行built with OpenSSL ...这一行应该显示Tongsuo的版本信息而不是系统自带的OpenSSL版本。在configure arguments:中应该能看到--with-openssl../Tongsuo。如果这里显示的还是系统OpenSSL说明编译时没有正确链接到Tongsuo需要回头检查configure步骤的路径是否正确。5. 国密证书的申请、生成与格式转换有了支持国密的Nginx接下来就需要国密证书了。证书通常由国密CA机构签发。这里我们分两种情况说明使用权威CA证书和自制测试证书。5.1 从国密CA机构申请证书如果你用于生产环境需要向获得资质的国密CA如CFCA、上海CA等申请证书。申请流程和普通SSL证书类似但密钥对必须是SM2算法生成的。CA通常会提供一个包含以下文件的证书包server_sign.crt 签名证书用于身份认证server_sign.key 签名证书的私钥server_enc.crt 加密证书用于密钥交换在NTLS双证书模式下需要server_enc.key 加密证书的私钥可能还有CA的中间证书和根证书。5.2 使用Tongsuo生成测试证书SM2单证书对于测试和学习我们可以用Tongsuo自己生成一个SM2自签名证书。cd /usr/local/nginx_gm/conf sudo mkdir -p gm_certs cd gm_certs # 1. 生成SM2私钥 sudo /usr/local/tongsuo/bin/openssl ecparam -genkey -name SM2 -out sm2.key # 2. 生成证书签名请求(CSR) sudo /usr/local/tongsuo/bin/openssl req -new -key sm2.key -out sm2.csr -sm3 -sigopt distid:1234567812345678 # 会交互式地输入国家、组织、通用名(域名)等信息。“-sm3”指定摘要算法“-sigopt”设置SM2用户标识测试时可随意。 # 3. 自签名生成证书 sudo /usr/local/tongsuo/bin/openssl x509 -req -days 365 -in sm2.csr -signkey sm2.key -out sm2.crt -sm3 -sigopt distid:1234567812345678这样就得到了测试用的国密证书sm2.crt和私钥sm2.key。5.3 证书格式问题与转换国密证书和密钥通常使用PEM格式-----BEGIN CERTIFICATE-----。但有时你拿到的可能是DER、P7B或PFX格式。Tongsuo的openssl命令可以处理大部分转换。一个常见的坑是私钥格式。有些工具生成的SM2私钥可能是PKCS#8格式包裹的。使用前最好用Tongsuo的openssl检查一下sudo /usr/local/tongsuo/bin/openssl pkey -in sm2.key -text -noout如果显示-----BEGIN PRIVATE KEY-----且算法是SM2那就是PKCS#8格式Nginx可以直接使用。如果是-----BEGIN EC PRIVATE KEY-----也是可以的。如果遇到问题可以尝试转换# 将传统EC私钥转换为PKCS#8格式 sudo /usr/local/tongsuo/bin/openssl pkcs8 -topk8 -nocrypt -in sm2_ec.key -out sm2_pkcs8.key实操心得 生产环境证书到手后第一件事就是用/usr/local/tongsuo/bin/openssl验证证书和私钥是否匹配并且确认证书链完整。命令是sudo /usr/local/tongsuo/bin/openssl verify -CAfile CA证书链文件 你的服务器证书。很多连接问题都源于证书链不完整。6. Nginx国密SSL配置详解证书准备好了我们来配置Nginx。国密SSL配置与普通SSL大同小异但有一些专属指令。6.1 基础国密单证书配置假设我们将测试证书放在/usr/local/nginx_gm/conf/gm_certs/下编辑Nginx的主配置文件nginx.conf或其包含的server块server { listen 443 ssl; server_name your.domain.com; # 指定国密证书和私钥 (SM2) ssl_certificate /usr/local/nginx_gm/conf/gm_certs/sm2.crt; ssl_certificate_key /usr/local/nginx_gm/conf/gm_certs/sm2.key; # 强制使用国密套件 ssl_ciphers ECC-SM2-WITH-SM4-SM3:ECDHE-SM2-WITH-SM4-SM3; ssl_protocols TLSv1.2 TLSv1.3; # TLSv1.1及以下不支持国密 # 优化SSL性能与安全 ssl_session_cache shared:SSL:10m; ssl_session_timeout 10m; ssl_prefer_server_ciphers on; ... # 其他location等配置 }关键配置解析ssl_ciphers 这里配置了国密算法套件。ECC-SM2-WITH-SM4-SM3是常见的国密套件标识。这是与普通配置最大的不同点。你必须明确指定国密套件否则Nginx可能会默认使用国际套件导致握手失败。ssl_protocols 国密算法通常在TLSv1.2及以上版本中得到完整支持。6.2 国密双证书NTLS配置在某些更严格的场景如金融网银会要求同时使用签名证书和加密证书这就是NTLS双证书模式。配置如下server { listen 443 ssl; server_name your.domain.com; # 签名证书和密钥 ssl_certificate /path/to/server_sign.crt; ssl_certificate_key /path/to/server_sign.key; # 加密证书和密钥 (NTLS专用指令) ssl_enc_certificate /path/to/server_enc.crt; ssl_enc_certificate_key /path/to/server_enc.key; # 启用NTLS并指定套件 ssl_ntls on; ssl_ciphers ECC-SM2-WITH-SM4-SM3; ssl_protocols TLSv1.2; ... # 其他配置 }注意ssl_ntls on;和ssl_enc_certificate指令这是双证书模式特有的。6.3 配置检查与Nginx启动配置完成后务必测试配置文件语法sudo /usr/local/nginx_gm/sbin/nginx -t -c /usr/local/nginx_gm/conf/nginx.conf如果显示“syntax is ok”和“test is successful”就可以启动了sudo /usr/local/nginx_gm/sbin/nginx7. 连接测试与问题深度排查服务启动后测试是验证成功与否的唯一标准。7.1 使用支持国密的客户端测试普通浏览器Chrome, Firefox和curl默认不支持国密。我们需要使用专门的工具。使用Tongsuo的s_client测试sudo /usr/local/tongsuo/bin/openssl s_client -connect localhost:443 -servername your.domain.com -ciphersuites ECC-SM2-WITH-SM4-SM3在输出中你应该看到“SSL handshake has read ... bytes and written ... bytes”以及“New, TLSv1.2, Cipher is ECC-SM2-WITH-SM4-SM3”。如果握手成功并显示了国密套件恭喜你配置成功了使用国密浏览器测试 可以下载360安全浏览器、红莲花国密浏览器等专门支持国密的浏览器进行访问。7.2 常见问题与排查技巧实录即使步骤正确你也可能遇到问题。下面是我踩过的一些坑和解决方法问题1Nginx启动失败报错SSL_CTX_use_PrivateKey_file或PEM routines:PEM_read_bio:no start line排查 这是最常见的私钥或证书格式错误。解决用sudo cat命令检查证书和密钥文件内容确认PEM格式正确有正确的BEGIN/END行。确保Nginx进程通常是nginx用户有读取这些文件的权限。sudo chmod 644 *.crt *.key和sudo chown nginx:nginx *.crt *.key用户根据你的实际运行用户调整。使用Tongsuo的openssl验证私钥和证书是否匹配sudo /usr/local/tongsuo/bin/openssl pkey -in server.key -pubout | openssl x509 -in server.crt -pubkey -noout两者输出的公钥应该一致。问题2SSL握手失败客户端报错handshake failure或no shared cipher排查 客户端和服务器没有协商出共同的密码套件。解决检查Nginx配置中的ssl_ciphers是否包含了正确的国密套件名称。套件名必须完全正确一个字符都不能错。确认客户端如s_client调用时也指定了相同的国密套件-ciphersuites参数。检查ssl_protocols是否至少包含了TLSv1.2。问题3使用s_client测试时报错unsupported protocol排查 可能是Tongsuo编译时没有启用NTLS但配置中却要求了双证书或者协议版本不匹配。解决重新检查Tongsuo编译时是否加入了enable-ntls选项。检查Nginx的ssl_protocols指令。对于纯国密单证书TLSv1.2通常是必须的。尝试简化配置先使用最基础的国密单证书配置进行测试排除双证书配置的干扰。问题4系统已有Nginx端口冲突排查 使用sudo netstat -tlnp | grep :443查看443端口是否被占用。解决 可以停用系统原有的Nginx/Apache或者修改我们编译的Nginx配置使用其他端口如8443进行测试。问题5Nginx-V显示仍然链接系统OpenSSL排查 编译时--with-openssl参数指向的路径错误或者编译环境中有残留的旧配置。解决在Nginx源码目录执行make clean彻底清理。重新运行configure确保--with-openssl指向Tongsuo源码目录的绝对路径。编译安装后再次验证。8. 性能调优与生产环境考量国密算法尤其是SM2的计算开销与ECC相当但在高并发场景下仍需关注一些优化点。8.1 SSL会话复用与普通TLS一样会话复用能极大减少握手带来的SM2签名验证开销。确保你的ssl_session_cache和ssl_session_timeout配置合理。ssl_session_cache shared:SSL:50m; # 根据内存调整50MB大约可缓存8万个会话 ssl_session_timeout 1h; # 会话超时时间8.2 国密硬件加速如果服务器负载非常高可以考虑支持国密算法的硬件加速卡如某些国产密码机或支持SM2/3/4的Intel QAT卡。这需要在编译Tongsuo时启用相应的硬件加速引擎支持如enable-qat_engine并在Nginx配置中通过ssl_engine指令指定。这部分配置较为复杂需要硬件厂商提供具体的驱动和文档。8.3 监控与日志在Nginx的http或server块中可以增加日志格式来记录SSL连接信息log_format ssl_log $remote_addr - $remote_user [$time_local] $request $status $body_bytes_sent $http_referer $http_user_agent $ssl_cipher $ssl_protocol; access_log /var/log/nginx/ssl_access.log ssl_log;这样在访问日志中就能看到每次连接使用的密码套件$ssl_cipher和协议版本$ssl_protocol方便监控国密连接的比例和状态。8.4 兼容性与降级策略除非强制要求否则在生产环境中可以考虑配置国密与国际算法双栈即同一个server块同时支持国密套件和RSA/ECC套件。客户端会根据自身能力协商。配置时在ssl_ciphers中同时列出国密套件和兼容的国际套件顺序代表优先级。但要注意这需要更仔细地测试和安全性评估。整个流程走下来从编译到配置再到排错最深的体会是“细节决定成败”。国密生态毕竟不像国际标准那样有海量的现成教程和踩坑记录每一个参数、每一个路径、每一个证书格式都可能成为拦路虎。最有效的办法就是严格遵循官方文档Tongsuo的Wiki写得不错并且每完成一步都立刻用工具验证结果。当你看到s_client握手成功并显示出ECC-SM2-WITH-SM4-SM3那一行时所有的折腾都值了。
