Python 对接指南

本页采用 gmssl==3.2.2。该包 API 较底层且版本行为有限，适合已有系统互操作验证，不应据此推导其已完成独立安全审计。仓库 fixture 使用隔离虚拟环境安装固定版本。

安装与验证

python -m venv .venv
# Windows: .venv\Scripts\python -m pip install -r requirements.txt
# Linux/macOS: .venv/bin/python -m pip install -r requirements.txt
python verify_vectors.py

仓库统一命令：

npm run docs:test-examples

核心示例：

from gmssl import func, sm3, sm4

# 1. SM3 摘要：计算标准输入 abc 的摘要。
digest = sm3.sm3_hash(func.bytes_to_list(b"abc"))
expected_sm3 = "66c7f0f462eeedd9d1f2d46bdc10e4e24167c4875cf2f7a2297da02b8f4ba8e0"

# 2. SM3 向量断言：结果必须等于公开固定值。
if digest != expected_sm3:
    raise AssertionError(f"SM3 vector mismatch: {digest}")

# 3. 准备 SM4 单分组向量：固定 16 字节 key 和 plaintext。
key = bytes.fromhex("0123456789abcdeffedcba9876543210")
plaintext = bytes.fromhex("0123456789abcdeffedcba9876543210")

# 4. 初始化 SM4 加密方向：这里只验证单分组结果。
cipher = sm4.CryptSM4()
cipher.set_key(key, sm4.SM4_ENCRYPT)

# 5. SM4 加密：gmssl 会为 ECB 调用自动加入填充。
ciphertext = bytes(cipher.crypt_ecb(plaintext))

# 6. SM4 向量断言：只比较固定输入对应的第一个密文分组。
if ciphertext[:16].hex() != "681edf34d206965e86b3e94f536e4246":
    raise AssertionError("SM4 vector mismatch")

CryptSM4() 必须先调用 set_key()。crypt_ecb() 默认加入填充，因此固定单分组向量只比较第一分组；业务协议应显式测试完整填充和解密行为。

SM2 边界

Python gmssl 常见 SM2 接口使用裸 hex 私钥、公钥和整数 mode，但不同版本对 C1 前缀、C1C2C3/C1C3C2、签名是否预摘要的约定不直观。不要仅凭“都叫 SM2”直接上线。

至少固定：

• 公钥是 x || y 还是 04 || x || y。
• 密文是 C1C3C2 还是 C1C2C3，C1 是否携带 04。
• 签名是 raw r || s 还是 DER。
• 是否计算 SM3(ZA || M)，以及双方 userId。

跨语言测试必须同时做双向加解密、双向签名验签和篡改拒绝。普通 SM3 摘要不能用于存储用户密码。

版本与部署

• 固定 requirements.txt，在 CI 中从干净 venv 安装。
• 不把私钥写进源码、日志或测试失败输出。
• 升级 gmssl 后先跑 fixture，再跑业务级 SM2/SM4 协议测试。