dsh-gm-crypto
v0.1.0
Published
Chinese national cryptography (GM/SM) toolkit for DeepSeek Harness: SM3 hash (GB/T 32905-2016) with HMAC-SM3, SM4 block cipher (GB/T 32907-2016) in ECB/CBC with PKCS7 padding, and cryptographically secure random (bytes/int/string with rejection sampling t
Maintainers
Readme
dsh-gm-crypto
面向 DeepSeek Harness 生态的国密算法工具箱(零运行时依赖、纯 JS、离线、确定性):SM3 密码杂凑(含 HMAC-SM3)、SM4 分组加解密(ECB/CBC + PKCS7)、密码学安全随机数。不联网、不存储、不依赖任何系统密码库,算法从标准独立实现。
功能说明
| 工具 | 作用 | 返回 |
|---|---|---|
| sm3_hash | SM3 杂凑 / HMAC-SM3 | 256 位摘要(hex/base64),带 key 时走 HMAC |
| sm4_crypt | SM4 加解密(ECB/CBC) | 密文/明文(hex/base64)+ 字节数与模式回显 |
| gm_random | 安全随机(bytes/int/string) | 随机字节、区间整数、指定字符集字符串 |
算法依据:
- SM3(GB/T 32905-2016 / GM/T 0004-2012):输出 256 位,Merkle-Damgård 结构,512 位分组、64 轮压缩;HMAC-SM3 按分组长度 64 字节的标准构造
- SM4(GB/T 32907-2016 / GM/T 0002-2012):128 位分组、128 位密钥、32 轮非线性迭代;解密为轮密钥逆序;支持 ECB/CBC 工作模式与 PKCS7 填充
- 安全随机:基于
node:crypto.randomBytes,整数与字符串用拒绝采样消除取模偏差(不用Math.random,不裸%)
正确性验证(三重): 标准测试向量逐字符比对 + 常量自检(S 盒双射、CK 生成公式)+ 与 OpenSSL(Node 内置 sm3/sm4-ecb/sm4-cbc)大规模 fuzz 逐字节比对。详见「版本说明」。
安装
# 从 npm 安装
dsh plugin --profile web add dsh-gm-crypto# 本地开发调试(Debug patch):新建 debug.patch.yml
# - insert:
# - id: gm-crypto
# name: "E:/dsh-plugins/dsh-gm-crypto/index.js"使用说明
1. sm3_hash —— SM3 杂凑 / HMAC
sm3_hash({ data: "abc" })
# → algorithm:SM3, digest_bits:256, digest:"66c7f0f4...8f4ba8e0"
sm3_hash({ data: "message", key: "secret" })
# → algorithm:HMAC-SM3, digest:"..."(消息认证码)
sm3_hash({ data: "616263", input_format: "hex" })
# 输入按十六进制理解,与文本 "abc" 同结果
sm3_hash({ data: "abc", output_format: "base64" })
# 摘要以 base64 返回参数:data(必填,字符串)、input_format(text/hex/base64,默认 text)、output_format(hex/base64,默认 hex)、key(可选,传入即走 HMAC-SM3)。
2. sm4_crypt —— SM4 加密 / 解密
sm4_crypt({
op: "encrypt", data: "国密 SM4 测试",
key: "0123456789abcdeffedcba9876543210",
mode: "cbc", iv: "000102030405060708090a0b0c0d0e0f"
})
# → result 为密文(默认 hex),output_bytes 为 16 的整数倍
sm4_crypt({
op: "decrypt", data: "<上面的密文>", input_format: "hex",
key: "0123456789abcdeffedcba9876543210",
mode: "cbc", iv: "000102030405060708090a0b0c0d0e0f"
})
# → result 为明文字节(默认 hex),并附 as_text(可 UTF-8 解码时)参数:data/key/op(必填),mode(ecb/cbc,默认 cbc)、iv(CBC 必填,16 字节 hex)、padding(pkcs7/none,默认 pkcs7)、input_format/output_format。
- key/iv 一律用十六进制:128 位 = 32 个 hex 字符。
- padding=none 时数据长度必须为 16 字节整数倍(ECB 加密、任何解密都要求整块)。
- 解密成功但填充校验失败 → 抛「密钥错误或密文被篡改」,这是密文完整性的被动检测,不是消息认证码(要认证用 HMAC-SM3 或上 AEAD)。
3. gm_random —— 安全随机
gm_random({ type: "bytes", length: 32 })
# → value(64 位 hex),可作 SM4 密钥/IV
gm_random({ type: "int", min: 1, max: 6 })
# → value ∈ [1,6],拒绝采样保证均匀
gm_random({ type: "string", length: 16, charset: "hex" })
# charset 取 digits/lower/upper/alnum/hex 或任意自定义字符序列典型场景
- 国密合规改造自检:把系统里旧的 MD5/SHA 摘要换成 SM3,先用
sm3_hash对齐参考实现(OpenSSL/BouncyCastle)的产出,验证迁移口径一致 - 敏感字段本地加密:政务/金融行业表单里的身份证号、银行卡号落库前用
sm4_crypt(CBC + 随机 IV)加密;配合 dsh-cn-toolkit 先做格式校验 - 接口签名/防篡改:对接国密网关时用
sm3_hash(key=...)生成 HMAC-SM3 报文认证码 - 密钥/令牌生成:
gm_random(bytes)出 128 位 SM4 密钥、gm_random(string)出会话令牌,避免用不安全的Math.random - 密评材料取证:等保/密评要求「采用商用密码算法」,本插件提供可离线复算、可对标准向量自证的 SM3/SM4 能力
安全边界
- 纯 JS 实现,不抗侧信道:S 盒查表、密钥相关分支会使执行时间与密钥相关。本插件面向离线脚本/开发联调/合规自检;运行在不可信环境(可被观测计时/缓存的攻击者)时不要依赖它保护长期密钥——生产密钥运算应走经认证的硬件密码模块或常量时间库。
- ECB 模式固有弱点:相同明文块得到相同密文块,会泄露数据模式。仅在对接方强制要求时用;其余一律 CBC(或考虑带认证的封装)。
- CBC 不提供完整性:CBC 解密只能被动发现坏填充,挡不住刻意篡改。需要「加密且认证」请另用 HMAC-SM3 做先认证后加密(Encrypt-then-MAC),或上经认证的分组模式。
- IV 必须随机且不复用:同一密钥下重复 IV 会破坏 CBC 语义安全;请用
gm_random生成。 - 不含 SM2/SM9:本版只做 SM3/SM4/随机(对称+杂凑)。SM2 是非对称椭圆曲线算法(签名/密钥交换/公钥加密),依赖大数模运算,留 v0.2。
- 不回显密钥:
gm_random的随机值只出现在本次返回里,插件不落盘、不缓存;调用方负责密钥的保管与销毁。 - 完全离线:不联网、不调用任何系统密码库;
sm3/sm4_*的 OpenSSL 比对仅存在于测试,运行时零外部依赖。
版本说明
- 0.1.0(2026-10-29):首版。
sm3_hash(SM3 + HMAC-SM3)/sm4_crypt(ECB/CBC + PKCS7)/gm_random(bytes/int/string,拒绝采样)三工具;2014 条测试断言全绿(真实 dsh-tools 包装层环境)。正确性三重验证:- 标准向量:SM3
abc→66c7f0f4...8f4ba8e0、64×abcd→debe9ff9...9c0c5732(GB/T 32905 附录 A);SM4 附录 A.1 单次加密681edf34d206965e86b3e94f536e4246,100 万次链式迭代前 8 字节595298c7c6fd271f吻合,复合过程与 OpenSSL 前 5000 次逐字节一致。 - 常量自检:SM4 S 盒为 256 字节双射;轮常量 CK 满足生成公式
ck[i][j]=(4i+j)×7 mod 256。 - 交叉 fuzz:SM3 400 轮、HMAC-SM3 150 轮、SM4 ECB/CBC 各 300 轮,与 Node 内置 crypto(OpenSSL 3.x)随机输入逐字节比对全部一致。
- 标准向量:SM3
- 已知边界:不实现 SM2/SM9/ZUC;纯 JS 不抗侧信道(见安全边界);不提供 AEAD 认证加密模式。
RoadMap
- v0.2:SM2 椭圆曲线(GB/T 32918)——密钥对生成、数字签名/验签(含 SM3 摘要前置 ZA);
sm3_file(大文件流式杂凑,分块读取) - v0.3:SM2 公钥加密(C1C3C2)与密钥交换;SM4 增加 CTR/GCM 模式,提供 Encrypt-then-MAC 高层封装
- v0.4:SM9 标识密码(GB/T 38635)评估与子集实现;常量时间查表改造(抵御简单计时侧信道)
其他插件集成说明
- dsh-cn-toolkit:证件号/卡号先
idcard_check/bankcard_check校验格式,再sm4_crypt加密落库——校验与加密两件套 - dsh-hash-checksum:hash-checksum 管通用摘要(SHA/MD5/CRC),本插件管国密(SM3/SM4);算法族不同、互不重叠
- dsh-base64-codec:SM4 密文以 hex/base64 交付,跨系统搬运时用 base64-codec 统一编码口径
- dsh-credential-scan:credential-scan 扫密钥明文泄漏,本插件负责把敏感字段加密——一个防外泄一个做保护
- dsh-json-yaml-toolkit:把
sm4_crypt产出的密文与元信息(mode/iv/tag)组织成结构化配置字段
FAQ
Q1:为什么不用 Node 内置 crypto 的 sm3/sm4,还要纯 JS 重写一遍? 内置 crypto 依赖底层 OpenSSL 编译开关——某些精简运行环境(受限容器、裁剪的 Node 发行版、跨平台交付)未必带国密算法。本插件零运行时依赖、行为自洽,并在测试里反过来用内置 crypto 作参照验证正确性。两者是「可移植实现 + 权威 oracle」的关系。
Q2:SM4 密钥/IV 为什么只收十六进制?
128 位密钥本质是 16 字节。hex 是字节最无歧义的文本表示(不受编码/字符集影响)。gm_random({type:"bytes",length:16}) 直接产出可用 hex 密钥。传错长度或非法 hex 会明确报错,不会静默截断。
Q3:解密报「填充校验失败」是 bug 吗? 不是,这通常是密钥错误或密文被改动的正确表现。PKCS7 去填充会校验末尾字节,不吻合即判定失败。确认 key/iv/mode/padding 四项与加密时完全一致;若是 ECB 且加密用了 padding=none,解密也要相应设为 none。
Q4:能拿 SM4-CBC 直接当「加密+认证」用吗? 不能。CBC 不抗主动篡改(无完整性标签)。要认证请另算 HMAC-SM3(先加密后对密文认证),或等 v0.3 的 GCM/Encrypt-then-MAC 封装。把 CBC 当认证加密是用错的典型。
Q5:纯 JS 的 SM4 慢,能用来加密大文件吗?
不适合热路径。纯 JS 分组密码吞吐远低于带硬件加速的实现,本插件定位是合规自检、字段级加密、联调对拍。大文件流式处理在 v0.2 的 sm3_file(至少摘要走流式)之后再评估是否值得内置加解密流。
Q6:这个实现能过密评吗? 本插件提供符合国密标准的算法实现且可对标准向量自证,可作为「采用商用密码算法」的技术材料之一。但密评看的是密码产品资质、密钥全生命周期管理、算法调用合规等系统工程,软件算法正确 ≠ 密评通过,需结合具备资质的密码模块与流程。
