首页/资讯中心/详情

Nginx国密证书配置实战：从编译到部署的完整指南

Nginx国密证书配置实战：从编译到部署的完整指南
📅 发布时间：2026/6/21 4:36:51

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，有两种主流方式：

  1. 动态模块： 寻找或编译一个支持国密的SSL动态模块（如ngx_http_gm_ssl_module），在Nginx配置中加载。这种方式相对简单，但模块的可用性和稳定性依赖第三方。
  2. 静态编译： 将支持国密的密码库（如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-devel

3.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 编译与安装Tongsuo

Tongsuo需要先被编译和安装到系统目录（如/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：这是一个关键选项。NTLS（National 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="..."： 传递给Tongsuo（OpenSSL）的配置选项，这里我们再次申明安装前缀和启用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

在输出的巨长信息中，你需要重点关注两行：

  1. built with OpenSSL ...这一行应该显示Tongsuo的版本信息，而不是系统自带的OpenSSL版本。
  2. 在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/nginx

7. 连接测试与问题深度排查

服务启动后，测试是验证成功与否的唯一标准。

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 常见问题与排查技巧实录

即使步骤正确，你也可能遇到问题。下面是我踩过的一些坑和解决方法：

问题1：Nginx启动失败，报错SSL_CTX_use_PrivateKey_file或PEM routines:PEM_read_bio:no start line

  • 排查： 这是最常见的私钥或证书格式错误。
  • 解决：
    1. 用sudo cat命令检查证书和密钥文件内容，确认PEM格式正确（有正确的BEGIN/END行）。
    2. 确保Nginx进程（通常是nginx用户）有读取这些文件的权限。sudo chmod 644 *.crt *.key和sudo chown nginx:nginx *.crt *.key（用户根据你的实际运行用户调整）。
    3. 使用Tongsuo的openssl验证私钥和证书是否匹配：sudo /usr/local/tongsuo/bin/openssl pkey -in server.key -pubout | openssl x509 -in server.crt -pubkey -noout，两者输出的公钥应该一致。

问题2：SSL握手失败，客户端报错handshake failure或no shared cipher

  • 排查： 客户端和服务器没有协商出共同的密码套件。
  • 解决：
    1. 检查Nginx配置中的ssl_ciphers是否包含了正确的国密套件名称。套件名必须完全正确，一个字符都不能错。
    2. 确认客户端（如s_client）调用时也指定了相同的国密套件（-ciphersuites参数）。
    3. 检查ssl_protocols是否至少包含了TLSv1.2。

问题3：使用s_client测试时，报错unsupported protocol

  • 排查： 可能是Tongsuo编译时没有启用NTLS，但配置中却要求了双证书，或者协议版本不匹配。
  • 解决：
    1. 重新检查Tongsuo编译时是否加入了enable-ntls选项。
    2. 检查Nginx的ssl_protocols指令。对于纯国密单证书，TLSv1.2通常是必须的。
    3. 尝试简化配置，先使用最基础的国密单证书配置进行测试，排除双证书配置的干扰。

问题4：系统已有Nginx，端口冲突

  • 排查： 使用sudo netstat -tlnp | grep :443查看443端口是否被占用。
  • 解决： 可以停用系统原有的Nginx/Apache，或者修改我们编译的Nginx配置，使用其他端口（如8443）进行测试。

问题5：Nginx-V显示仍然链接系统OpenSSL

  • 排查： 编译时--with-openssl参数指向的路径错误，或者编译环境中有残留的旧配置。
  • 解决：
    1. 在Nginx源码目录执行make clean彻底清理。
    2. 重新运行configure，确保--with-openssl指向Tongsuo源码目录的绝对路径。
    3. 编译安装后再次验证。

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那一行时，所有的折腾都值了。