guomi

# Security Policy and Usage Boundaries

Guomi 是纯 Elixir 的 SM2、SM3、SM4 实现。除非发布说明另有明确记录，本项目没有密码产品认证，也没有完成独立第三方安全审计。

## 漏洞报告

请不要在公开 Issue 中披露尚未修复的安全漏洞。通过 GitHub Security Advisory 私下报告，并附上受影响版本、复现方式、潜在影响和建议修复方向。

## API 安全边界

### SM2

- 新代码应使用 `sign_standard/3`、`verify_standard/4`，并由协议显式规定相同的 user ID。
- 新代码应使用 `encrypt_standard/2`、`decrypt_standard/2`；它们采用标准 SM3 KDF 和 `C1 || C3 || C2` 裸格式。
- `sign/2`、`verify/3` 不计算 ZA，只为旧 Guomi 数据和脚本保留。
- `encrypt/2`、`decrypt/2` 会对长消息重复 32 字节掩码，只为旧数据迁移保留，不得用于敏感数据。
- 标准与旧解密入口不会互相猜测或回退。调用方必须根据可信的格式元数据选择入口。
- SM2 适合加密短密钥材料，不适合直接加密大文件。大数据应使用经过审查的混合加密协议。
- 标准 API 已覆盖公开向量和 OpenSSL 互操作，但这不等同于独立安全审计。

### SM4

- ECB 只适合标准向量测试或严格受控的遗留兼容，不适合一般消息。
- CBC 和 CTR 只提供机密性，不检测篡改。不得把成功解密或成功去除 padding 当作消息可信。
- CBC 的 IV 必须不可预测且不得在同一密钥下复用。
- CTR 的初始 counter 在同一密钥下必须唯一；复用会泄露明文之间的 XOR 关系。
- 需要完整性时，优先使用协议已经定义并经审查的认证加密方案。如果协议必须使用裸 SM4 CBC/CTR，应在协议层采用独立密钥的 encrypt-then-MAC，认证算法及标签长度必须由协议固定，并覆盖版本、算法标识、IV/counter、关联元数据和完整密文。
- 本库目前不提供通用 SM4 encrypt-then-MAC 高层 API，避免在没有协议上下文时规定密钥派生、标签编码或重放语义。应用不应自行拼接未经评审的组合。

### SM3

- SM3 是无密钥哈希函数，不等同于 MAC、密码散列或密钥派生函数。
- 需要消息认证时使用协议指定的 MAC；需要存储密码时使用专用、带盐且成本可调的密码哈希方案。

## 密钥、随机数与侧信道

- 私钥和对称密钥必须由受信任的密钥管理系统生成、存储和轮换，不应写入日志、命令历史或错误信息；CLI 传入 `--private-key` 会落入 shell 历史与进程列表，生产环境优先使用文件或环境变量读取。
- SM2 临时标量和密钥使用 Erlang `:crypto.strong_rand_bytes/1`。部署方仍需保证操作系统随机源正常。
- 纯 Elixir 大整数和曲线运算没有声明为常量时间。对本地攻击者、共享主机或高价值密钥场景，不应假定可抵抗缓存、调度和计时侧信道。热点剖析见 `bench/sm2_hotspot_analysis.md`（`mod/2` 占 55% OWN）。
- `secure_compare` 只减少摘要比较中的早退差异，不能使整个 SM2 解密路径成为常量时间。
- 解密端应限制输入大小（例如 `max_ciphertext = 65+32+max_plaintext`）、调用频率和错误可见性，防止资源消耗与错误预言机被协议放大；SM4 `decrypt` 的 `:invalid_padding` 与 `:invalid_block_size` 可区分，若直接暴露给远端则构成 padding oracle，建议网关层统一映射为 `:decryption_failed`。
- 本项目自审查报告见 `SECURITY_REVIEW.md`（2026-08-19），仍未替代第三方审计。

## 明确不适用场景

- 需要经过国家密码管理认证、FIPS 验证或硬件密钥隔离的系统。
- 无法接受纯 Elixir 大整数侧信道风险的多租户或敌对共址环境。
- 直接加密大文件、数据库备份或无限长度网络流量。
- 仅依赖裸 SM4 CBC/CTR 提供身份认证、完整性或防重放的协议。
- 无可靠格式版本信息却需要自动区分旧 Guomi 密文和标准 SM2 密文的系统。

## 发布前安全检查

- 标准向量、负面测试和 OpenSSL 互操作测试通过。
- 新公开 API 的输入上限、错误分类、二进制格式和迁移影响已记录。
- release tag 与包版本一致，最低支持的 Elixir/OTP 组合通过 CI。
- 涉及密码学构造、随机数或解析边界的重大变更应在发布前接受独立审查。