算法选择与协议设计

算法名称不能替代协议设计。上线前必须同时确定算法、工作模式、编码、密钥生命周期、随机数来源和错误处理。

能力对应

需求	推荐入口	不适合的做法
身份签名	SM2 签名或协议要求的国际签名算法	把摘要值当作数字签名
小数据/会话密钥封装	SM2 加密	用 SM2 直接加密大文件或长业务报文
通用认证加密	SM4-GCM 或 SM4-CCM	新协议使用 ECB，或只加密不认证
旧协议块加密	明确参数的 CBC/CTR/CFB/OFB	重用 IV/nonce，或省略 MAC
国密摘要	SM3	把普通摘要当作来源认证；直接用一次 SM3 存储用户密码
消息认证	HMAC-SM3 或 HMAC-SHA-2	hash(key + message) 自制 MAC
3GPP 机密性/完整性	EEA3/EIA3	把通用 ZUC IV 与 EEA3/EIA3 参数混用
国际摘要兼容	SHA-256/384/512	新安全协议继续使用 SHA-1

关键决策

SM2

跨系统必须固定：

• userId；当前空字符串会回落到 DEFAULT_USER_ID，不能表达真实空 ID。
• 标准签名使用 SM3(Z || M)；no-Z 入口只用于迁移已存在的非标准旧协议。
• 密文排列 C1C3C2 或 C1C2C3。
• 公钥是压缩点还是非压缩点。
• 签名是 raw r || s 还是 ASN.1 DER。
• 密文和签名使用 hex 还是 Base64。

SM4

新业务优先 AEAD。GCM/CCM 的 nonce、AAD、tag 都属于协议字段，必须与密文一起保存或传输。相同密钥下不得重用 nonce。

CBC/CTR/CFB/OFB 只提供机密性，业务协议还需要独立、正确组合的 MAC。ECB 会暴露重复分组，不应用于敏感业务数据。

ZUC

通用 zucEncrypt 接收 16 字节 key/IV。3GPP 场景应使用 eea3Encrypt 和 eia3，由协议提供 COUNT、BEARER、DIRECTION 和消息 bit length。旧 eea3 只保留为 word-aligned 密钥流兼容入口。

合规边界

本项目文档描述实现与互操作边界，不构成密码产品认证、行业准入意见或法律建议。是否必须采用特定算法、模块或认证产品，应依据部署地区、行业规则、系统等级和主管部门要求单独评估。

性能边界

不要使用文档中的通用数字估算生产容量。JavaScript 引擎、硬件、消息大小、工作模式和并发模型都会改变结果。使用仓库基准命令在目标环境采样，并同时验证正确性和内存占用。