安全边界

上线前提

GMKitX 尚未完成独立第三方安全审计，也不负责密钥托管、证书信任、协议防重放或运行环境加固。请勿把单元测试通过等同于完成安全评估。

随机数

密钥生成、SM2 加密和签名依赖随机数。默认策略是 warn：缺少 CSPRNG 时打印一次警告并继续兼容运行。这是为了不直接破坏受限小程序，但降级随机源不具备密码学安全性。

安全敏感应用应选择其一：

import { configureRNG, setCustomRNG } from 'gmkitx';

configureRNG('strict');

// 或在受限平台注入经过平台保证的安全随机源：
setCustomRNG((length) => platformSecureRandom(length));

不得在生产环境注入固定种子或确定性测试 RNG。
自定义 RNG 必须返回精确长度的 Uint8Array；库会拒绝错误类型和长度。Web Crypto 请求超过 65536 字节时会自动分块，避免把平台单次调用上限误判为“没有 CSPRNG”。

密钥生命周期

• 不要把私钥、SM4 key 或 HMAC key 写入源码、URL、日志和前端持久化存储。
• 浏览器端长期密钥会暴露给同源脚本、扩展、XSS 和调试工具；高价值密钥优先保留在服务端、HSM 或受控密钥服务中。
• Uint8Array.fill(0) 只能尽力覆盖当前缓冲区，不能保证 JavaScript 引擎、复制值或垃圾回收内存中的所有副本被清除。
• 定义密钥版本、轮换、吊销、备份和灾难恢复流程。

IV 与 nonce

模式	要求
SM4-GCM	同一 key 下 nonce 必须唯一；推荐 12 字节
SM4-CCM	同一 key 下 nonce 必须唯一；长度 7-13 字节
SM4-CTR/CFB/OFB/CBC	同一 key 下不得按会泄露模式的方式重复 IV；具体生成方式应写入协议
ZUC	同一 key/IV 会产生相同密钥流，严禁复用

随机 nonce 需要评估碰撞概率；高吞吐系统更适合使用持久化计数器、分区前缀或经过证明的 nonce 分配方案。

认证与错误处理

• 新协议优先 SM4-GCM/CCM，并在解密成功前不处理明文。
• CBC/CTR/CFB/OFB 和通用 ZUC 不提供认证，不能单独抵御篡改。
• 验签失败、tag 不匹配、SM2 C3 不匹配都应视为认证失败；不要继续使用输出。
• 对外错误响应不应泄露密钥、明文、完整堆栈或可用于构造解密预言的细粒度差异。

JavaScript 运行环境

JavaScript JIT、共享运行时和垃圾回收使严格常量时间和内存清除难以保证。对于侧信道威胁高、合规要求强或长期持有主密钥的系统，应评估经审计的 native 模块、受控 Java 服务或硬件密码模块。

漏洞报告

安全问题不要附带真实密钥或生产数据。优先通过仓库维护者提供的私密渠道报告；若只能使用 GitHub Issues，请先提交不含利用细节的最小说明。