Easy Encryption Tool工具AI优化

本文档记录 2025-02-16 对 easy_encryption_tool 的 Vibecoding 实践：基于 easy_gmssl 2.0.1 将国密算法（SM2、SM3、SM4、ZUC）及国密证书解析能力集成进工具，在保持与既有国际算法（AES、RSA、ECC、HMAC）一致风格与体验的前提下，实现国密与国际算法的统一入口。

一、总览与目标

easy_encryption_tool 原已支持国际算法：AES、RSA、ECC、HMAC、证书解析等。本次 Vibecoding 的目标是在不破坏既有体验的前提下，将国密算法对等接入，形成「国际 + 国密」双轨能力。

国密算法	对标国际算法	能力要点
SM4	AES	CBC、GCM 模式，密钥 16 字节，PKCS#7 填充
SM2	RSA	加解密、签名验签；多种密文格式、多种签名值格式
SM3	SHA-256 系列	Hash 摘要、HMAC
ZUC	流密码	单独作为流式加解密算法，密文与明文等长
国密证书	X.509	SM2 证书解析（PEM 格式）

设计原则：

新命令与既有命令保持相同的参数风格（-i 输入、-e base64、-f 文件、-o 输出等）
统一使用 command_perf.timing_decorator 做耗时统计
复用 common 模块的 base64、文件读写、bytes_to_str 等工具
easy_gmssl 为可选依赖，未安装时国密命令给出明确安装提示

二、SM4 对称加解密

2.1 定位

SM4 对标 AES，作为国密对称加密算法，支持 CBC 与 GCM 模式。

2.2 实现要点

密钥与 IV：密钥 16 字节，CBC 模式 IV 16 字节，GCM 模式 Nonce 12 字节；不足自动补齐，超出自动截取
填充：与 AES 一致，使用 PKCS#7
GCM：加密输出密文 + 16 字节 tag；解密需通过 -t 传入 tag
输入输出：支持字符串、base64、文件；加密输出 base64，解密支持明文/字节流

2.3 命令示例

1
2
3
4
5
6
7
8
# CBC 加密
easy_encryption_tool sm4 -m cbc -a encrypt -i hello,world

# GCM 加密（需保存 tag 用于解密）
easy_encryption_tool sm4 -m gcm -a encrypt -i hello,world

# GCM 解密
easy_encryption_tool sm4 -m gcm -a decrypt -i <cipher_b64> -e -t <tag_b64>

2.4 与 AES 的对应关系

参数	AES	SM4
模式	`-m cbc \| gcm`	`-m cbc \| gcm`
密钥长度	32 字节	16 字节
IV/Nonce	16/12 字节	16/12 字节
随机密钥	`-r`	`-r`
动作	`-a encrypt \| decrypt`	`-a encrypt \| decrypt`
GCM tag	`-t`	`-t`

三、SM2 非对称加解密与签名验签

3.1 定位

SM2 对标 RSA，作为国密非对称算法，支持加解密与签名验签。

3.2 密文格式

SM2 密文由 C1、C2、C3 三部分构成，支持多种排列与编码方式：

格式	说明
C1C3C2_ASN1	ASN.1 编码，顺序 C1-C3-C2（默认）
C1C3C2	裸字节，顺序 C1-C3-C2
C1C2C3_ASN1	ASN.1 编码，顺序 C1-C2-C3
C1C2C3	裸字节，顺序 C1-C2-C3

加密时可指定输出格式为 base64 或 hex；解密时需指定与加密一致的密文格式。

3.3 签名值格式

格式	说明
RS_ASN1	DER 编码的 r、s（默认）
RS	裸 64 字节：r(32) \|\| s(32)

3.4 子命令结构

与 RSA 类似，采用 Click Group：

1
2
3
4
5
sm2 generate   # 生成密钥对（私钥必须加密，密码 1–32 字节）
sm2 encrypt    # 公钥加密
sm2 decrypt    # 私钥解密
sm2 sign       # 私钥签名
sm2 verify     # 公钥验签

3.5 命令示例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# 生成密钥对
easy_encryption_tool sm2 generate -f demo -p mypassword

# 加密（指定密文格式与输出格式）
easy_encryption_tool sm2 encrypt -f demo_sm2_public.pem -i hello -m C1C2C3 -o hex

# 解密（hex 输入需 -x）
easy_encryption_tool sm2 decrypt -f demo_sm2_private.pem -i <cipher_hex> -x -m C1C2C3 -p mypassword

# 签名（RS 格式）
easy_encryption_tool sm2 sign -f demo_sm2_private.pem -i hello -m RS -p mypassword

# 验签
easy_encryption_tool sm2 verify -f demo_sm2_public.pem -i hello -s <sig_b64>

四、Hash 与 HMAC 扩展

4.1 新增 hash 命令

统一哈希入口，支持国密 SM3 及国际 SHA256、SHA384、SHA512：

1
2
3
easy_encryption_tool hash -i hello -a sha256
easy_encryption_tool hash -i hello -a sm3      # 需 easy_gmssl
easy_encryption_tool hash -i ./file.txt -f -a sha512

输入：字符串、base64（-e）、文件（-f）
输出：hex 格式摘要

4.2 HMAC 扩展

在既有 HMAC 命令上增加 SM3 支持：

算法	依赖	说明
sha256, sha384, sha512, sha3_*	标准库	原有能力
sm3	easy_gmssl	新增，密钥长度 16–64 字节

同时将 -h 改为 -a，避免与 Click 默认 --help 冲突。

1
easy_encryption_tool hmac -i hello -a sm3 -k mykey

五、ZUC 流密码

5.1 定位

ZUC（祖冲之）作为流密码，密文与明文等长，适合不允许密文膨胀的场景。

5.2 实现要点

密钥与 IV 均为 16 字节
加解密使用同一套接口（流密码特性）
支持字符串、base64、文件输入
输出：加密为 base64，解密根据明文是否可打印决定输出形式

5.3 命令示例

1
2
3
4
5
6
7
8
# 加密
easy_encryption_tool zuc -i hello -a encrypt

# 解密
easy_encryption_tool zuc -i <cipher_b64> -e -a decrypt

# 文件加解密
easy_encryption_tool zuc -i ./plain.bin -f -o ./cipher.bin -a encrypt

六、国密证书解析

6.1 扩展 cert-parse

在既有 cert-parse 命令上增加 -g / --gm-cert 选项，用于解析国密 SM2 证书：

1
easy_encryption_tool cert-parse -f sm2_cert.pem -e pem -g

仅支持 PEM 格式
输出：序列号、颁发者、主体、有效期、公钥类型（SM2）等
依赖 easy_gmssl 的 EasySm2Certificate

6.2 与标准证书的区分

场景	命令
RSA/EC 等国际证书	`cert-parse -f xxx.pem -e pem`
国密 SM2 证书	`cert-parse -f xxx.pem -e pem -g`

标准证书加载失败且为 PEM 时，会提示可尝试 -g 按国密证书解析。

七、依赖与安装

7.1 可选依赖

国密能力依赖 easy_gmssl >= 2.0.1，通过 extras_require 声明：

1
2
3
extras_require = {
    'gmssl': ['easy_gmssl>=2.0.1'],
},

7.2 安装方式

1
2
3
4
5
6
7
# 仅安装基础能力（AES、RSA、ECC、HMAC 国际算法等）
pip install easy-encryption-tool

# 安装国密能力
pip install easy-encryption-tool[gmssl]
# 或
pip install easy_gmssl

7.3 未安装 easy_gmssl 时的行为

执行国密相关命令（sm4、sm2、hash sm3、hmac sm3、zuc、cert-parse -g）时，会输出：

1
SM4 需要 easy_gmssl 库，请执行: pip install easy_gmssl

其他命令不受影响。

八、完整修改文件清单

文件	操作	说明
`easy_encryption_tool/sm4_command.py`	新增	SM4 CBC/GCM 加解密
`easy_encryption_tool/sm2_command.py`	新增	SM2 密钥生成、加解密、签名验签
`easy_encryption_tool/hash_command.py`	新增	统一 hash（SM3、SHA256/384/512）
`easy_encryption_tool/hmac_command.py`	修改	增加 SM3 HMAC，`-h` 改为 `-a`
`easy_encryption_tool/zuc_command.py`	新增	ZUC 流密码加解密
`easy_encryption_tool/cert_parse.py`	修改	增加 `-g` 国密证书解析
`easy_encryption_tool/main.py`	修改	注册 sm4、sm2、hash、zuc 等命令
`setup.py`	修改	`extras_require` 增加 gmssl
`easy_encryption_tool/tool_readme.md`	修改	更新命令列表与安装说明
`docs/VIBECODING_GMSSL_INTEGRATION_20250216.md`	新增	本文档

附录：命令总览

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
aes         aes 加解密（cbc/gcm）
sm4         国密 SM4 加解密（cbc/gcm）
hash        哈希摘要（SM3、SHA256/384/512）
hmac        HMAC（含 SM3）
rsa         RSA 加解密与签名验签
sm2         国密 SM2 加解密与签名验签
ecc         ECC 签名验签与密钥交换
zuc         ZUC 流密码加解密
random-str  随机字符串生成
cert-parse  证书解析（含国密 -g）
version     版本与运行时信息

文档生成于 easy_encryption_tool 国密算法 Vibecoding 集成实践，适用于 CLI 加密工具扩展与国密算法接入参考。

目录#

一、总览与目标#

二、SM4 对称加解密#

2.1 定位#

2.2 实现要点#

2.3 命令示例#

2.4 与 AES 的对应关系#

三、SM2 非对称加解密与签名验签#

3.1 定位#

3.2 密文格式#

3.3 签名值格式#

3.4 子命令结构#

3.5 命令示例#

四、Hash 与 HMAC 扩展#

4.1 新增 hash 命令#

4.2 HMAC 扩展#

五、ZUC 流密码#

5.1 定位#

5.2 实现要点#

5.3 命令示例#

六、国密证书解析#

6.1 扩展 cert-parse#

6.2 与标准证书的区分#

七、依赖与安装#

7.1 可选依赖#

7.2 安装方式#

7.3 未安装 easy_gmssl 时的行为#

八、完整修改文件清单#

附录：命令总览#

目录