📚 课程目录第4章环境准备

环境准备：把工具箱武装到位

这一章，咱们动手搭环境。

别小看这一步。我见过太多人，代码写完才发现库版本不对、编译报错、签名验签对不上。折腾半天，其实只是环境没配好。你想想看，多冤枉。

咱们的目标很明确：装好 GmSSL、带国密补丁的 OpenSSL 1.1.1、Python 侧的 gmssl-python 库，再把开发工具链调通。下面我一步步说，你跟着来就行。

4.1 为什么要装两个 SSL 库？

很多人第一次接触国密时会问：不是有 GmSSL 了吗，为什么还要碰 OpenSSL？

其实很简单。GmSSL 专门跑国密算法，干净利落。但很多 KMS、HSM、云平台底层是 OpenSSL 内核，它们需要加载国密引擎或补丁才能支持 SM2/SM4。如果你只在 GmSSL 上验证通过，到了生产环境对接 OpenSSL 系组件时，大概率会出问题。

我个人习惯两手都抓：用 GmSSL 做算法验证和原型开发，用带补丁的 OpenSSL 做生产模拟和对接测试。这样两头都稳。

    核心原则：GmSSL 是独立国密实现，OpenSSL + 国密补丁是系统级集成方案。两个都要装，两套都要会用。

4.2 安装 GmSSL

GmSSL 是北京大学开源的项目，支持 SM2、SM3、SM4、SM9 全套国密算法。安装过程很顺，基本不踩坑。

4.2.1 源码编译安装

# 下载源码（建议用 release 版本）
wget https://github.com/guanzhi/GmSSL/archive/refs/tags/v3.1.1.tar.gz
tar -zxvf v3.1.1.tar.gz
cd GmSSL-3.1.1

# 编译
mkdir build && cd build
cmake ..
make -j$(nproc)

# 安装到系统
sudo make install

# 验证
gmssl version

如果输出类似 GmSSL 3.1.1，就成功了。

小提示：我在某次项目中遇到编译时找不到 cmake，后来用 apt install cmake 补齐就好。GmSSL 依赖很少，基本不会卡住。

4.2.2 快速测试

# 生成 SM2 密钥对
gmssl sm2keygen -pass 1234 -out pub.pem -outform pem -out priv.pem -outform pem

# SM4 加解密
echo "hello gmssl" | gmssl sms4 -encrypt -pass 1234 -out cipher.bin
gmssl sms4 -decrypt -pass 1234 -in cipher.bin

能正常生成密钥、加解密，就说明 GmSSL 已经可用。

4.3 编译 OpenSSL 1.1.1 + 国密补丁

这一步稍微复杂点。OpenSSL 官方自 1.1.1 开始，其实已经内置了 SM2、SM3、SM4 的底层算法支持，但还不能直接通过命令行或 API 调 SM2 签名。所以我们需要补丁，把指令和引擎补齐。

我用的是 open-crypto 社区维护的 SM2/SM9 补丁包，兼容性最好。

4.3.1 下载与打补丁

# 下载 OpenSSL 1.1.1 源码
wget https://www.openssl.org/source/openssl-1.1.1w.tar.gz
tar -zxvf openssl-1.1.1w.tar.gz
cd openssl-1.1.1w

# 下载国密补丁
wget https://github.com/open-crypto/openssl-sm2-sm3-sm4/archive/refs/heads/master.zip
unzip master.zip -d patch_dir

# 打补丁
patch -p1 < patch_dir/openssl-sm2-sm3-sm4-master/patches/openssl-1.1.1_sm2sm3sm4.patch

注意：补丁文件可能随项目更新而变化。我曾经在 Ubuntu 20.04 上打补丁时发现补丁版本和 OpenSSL 源码版本不匹配，导致几行代码冲突。建议下载前先看 patch 文件第一行的 OpenSSL 版本号，完全对齐再打。

4.3.2 编译安装

# 配置，启用 SM2/SM3/SM4 支持
./config enable-sm2 enable-sm3 enable-sm4 enable-ec enable-ecdh enable-ecdsa \
          --prefix=/usr/local/openssl-gm

make -j$(nproc)
sudo make install

# 检查是否支持 SM2 曲线
/usr/local/openssl-gm/bin/openssl ecparam -list_curves | grep SM2

如果输出包含 SM2，说明补丁生效了。

4.3.3 验证 SM2 签名

# 生成 SM2 密钥
/usr/local/openssl-gm/bin/openssl ecparam -genkey -name SM2 -out sm2_priv.pem

# 导出公钥
/usr/local/openssl-gm/bin/openssl ec -in sm2_priv.pem -pubout -out sm2_pub.pem

# 签名
echo "data to sign" > data.bin
/usr/local/openssl-gm/bin/openssl dgst -sm3 -sign sm2_priv.pem -out sig.bin data.bin

# 验签
/usr/local/openssl-gm/bin/openssl dgst -sm3 -verify sm2_pub.pem -signature sig.bin data.bin

输出 Verified OK，就对了。

4.4 安装 Python 国密库

Python 侧我推荐用 gmssl-python。它是 GmSSL 的 Python 封装，接口简单，而且与 GmSSL 的命令行行为一致，调试起来很直观。

# 直接用 pip 安装
pip install gmssl-python

# 验证
python3 -c "import gmssl; print(gmssl.__version__)"

输出类似 3.1.0，就装好了。

4.4.1 快速测试 SM2 签名

from gmssl import sm2

# 生成密钥对
private_key, public_key = sm2.generate_keypair()

# 签名
msg = b"hello gmssl in python"
signature = sm2.sign(msg, private_key)

# 验签
valid = sm2.verify(msg, signature, public_key)
print("Signature valid:", valid)

输出 Signature valid: True，一切正常。

小提示：如果你习惯用 cryptography 库，也可以通过加载 GmSSL 引擎来调用国密算法。但说实话，gmssl-python 的学习成本更低，新手友好。

4.5 开发工具链配置

光有库还不够，开发工具链也得顺。我推荐以下配置：

工具	推荐版本	用途
Python	3.8 - 3.11	运行 Python 代码，对接 KMS SDK
CMake	≥ 3.15	编译 GmSSL 或第三方 C 扩展
VSCode / PyCharm	最新稳定版	IDE，断点调试、语法高亮、代码补全
Postman / curl	任意	测试 KMS REST API
Wireshark / tcpdump	任意	抓包分析 TLS 握手、国密套件协商

4.5.1 环境变量配置

如果你像我一样，同时装了多个版本 OpenSSL，记得把国密版 OpenSSL 的路径放到 PATH 和 LD_LIBRARY_PATH 里：

export PATH=/usr/local/openssl-gm/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/openssl-gm/lib:$LD_LIBRARY_PATH

我习惯把这行加到 ~/.bashrc 里，省得每次手动 source。

4.6 知识体系总览

下面这张图能帮你快速理清各组件之间的关系。为什么先装 GmSSL、再编译 OpenSSL 补丁、最后装 Python 库，一目了然：

4.7 验证整体联调

所有组件装完后，我建议跑一个端到端验证。用 GmSSL 生成密钥，OpenSSL 验签，Python 走 SDK 查询，确保整个链路上没有版本错配。

常见坑点：我曾在一台 CentOS 7 上发现 GmSSL 和 OpenSSL 导出的 SM2 公钥格式不同——GmSSL 默认用压缩格式，OpenSSL 用非压缩格式。验签前最好统一格式，否则死活验不过。

到这里，你的国密开发环境就搭稳了。代码写完可以直接跑，不会出现「我这行，你那不行」的窘境。后面的章节，我们会基于这套环境，一步步实现 SM2 密钥生成、SM4 加密、以及 KMS 对接。你只管跟着做，不会掉队。