guomi

# Roadmap

本文记录 Guomi 的后续工作方向。已发布版本的完成项与行为变化请查看 [CHANGELOG.md](CHANGELOG.md)。

当前 P0/P1/P2 基线实现与自动化验证均已完成（2026-08-19 自审查与热点分析已归档，见 `SECURITY_REVIEW.md` / `bench/sm2_hotspot_analysis.md`）；后续工作包括第三方审计等外部依赖，以及下方未勾选的高风险性能优化候选项，已完成项保留在本文中作为验收记录。

## 优先级说明

- **P0**：安全性、正确性或兼容性问题，应优先处理。
- **P1**：会显著改善公开 API、CLI 或发布质量的工作。
- **P2**：性能、扩展能力和长期维护工作。

## 已采用的执行顺序

1. 完成发布版本校验、最低版本 CI 和无效 CLI 选项清理。
2. 先形成 SM2 标准签名与新密文格式设计，再修改公开 API。
3. 实现版本化 SM2 密文、标准 KDF 和旧格式迁移策略。
4. 增加标准测试向量、跨实现测试和独立安全审查。
5. 统一 CLI 输入语义并补齐公开 API 与文档示例测试。
6. 最后处理基准、流式 API、证书解析与 SM9 调研。

## P0：SM2 标准兼容与安全迁移

### 标准签名 API

- [x] 设计标准兼容的 SM2 签名与验签 API，明确用户 ID 必须显式传入以及 ZA 的计算方式。
- [x] 决定第一阶段使用 raw `r || s`，DER 留作显式扩展，并避免静默改变现有 `sign/2`、`verify/3` 的兼容行为。
- [x] 增加 GB/T 32918.5 ZA/签名测试向量及 OpenSSL 双向签名互操作测试。

### 版本化密文与 KDF

- [x] 定义新的标准兼容密文格式，明确 C1/C2/C3 排列、点编码、空消息待互操作确认和显式解析规则。
- [x] 新增按消息长度扩展且不会重复掩码的标准 KDF 与显式标准加密 API；旧 API 保持原语义并明确记录兼容限制。
- [x] 为新旧密文定义不同的显式 API，并为未来持久化 envelope 预留版本字段，禁止解密时猜测格式。
- [x] 制定旧兼容格式的弃用和迁移策略；迁移完成前继续明确其长消息风险和非生产用途。
- [x] 增加 GB/T 32918.5 密文向量、畸形密文测试及 OpenSSL 双向加解密互操作测试。

### 完整性与安全边界

- [x] 为需要完整性保护的 SM4 使用场景记录协议级认证加密或独立密钥 encrypt-then-MAC 方案，并强调裸 CBC/CTR 仅提供机密性。
- [x] 对公开 API、密钥与随机数处理、错误行为和时间侧信道开展独立安全审查。见 `SECURITY_REVIEW.md`（2026-08-19，基于代码证据、负面测试与 eprof 热点剖析；结论：文档化边界内通过自审查，仍未达第三方审计标准，已回填 `SECURITY.md:35-42`）。
- [x] 在安全文档中记录当前验证范围、残余风险及明确不适用场景。

## P1：发布与测试质量

- [x] 在 release workflow 中校验 Git tag 与 `mix.exs` 版本一致，并在创建 Release 和发布 Hex 包前失败退出。
- [x] 增加受支持 Elixir/OTP 版本的 CI 矩阵，至少覆盖 README 声明的最低组合和当前主要组合。
- [x] 增加文档示例测试：库 API 使用 doctest，CLI 示例使用集成测试，避免 README、`cli.md` 与实际行为漂移。
- [x] 将 SM2 官方 ZA/签名向量和 OpenSSL 双向签名互操作纳入 CI；外部实现不可用时明确报告原因。
- [x] 提供严格的本地 OpenSSL 互操作脚本，覆盖 SM3、SM4 ECB/CBC/CTR 和标准 SM2；OpenSSL 能力缺失时失败退出。
- [x] 在 CI 中执行严格 OpenSSL 互操作脚本，并为核心库设置 85% 覆盖率门槛；CLI 由黑盒集成测试单独验证。

## P1：API 与 CLI 完善

- [x] 移除当前已解析但无实际行为的 SM2 `--hex` 选项，并对该无效选项返回明确错误。
- [x] 统一 CLI 中单参数“文件路径”和“消息文本”的语义：位置参数表示消息文本，文件输入使用显式 `--file`，并记录迁移方法。
- [x] 为 CLI 增加 SM4 CTR 模式，使用独立的 `--counter` 接收固定 16 字节大端初始计数器，并拒绝 padding 选项。
- [x] 为所有公开函数补充 `@doc`、参数与二进制格式、返回值、错误原因和安全限制说明。
- [x] 统一无效 iodata、密钥、签名和密文的错误分类，避免把非密钥输入错误报告为 `:invalid_key`。

## P2：性能与扩展

- [x] 完善现有 `bench/bench.exs`：记录架构、操作系统、Elixir/OTP/ERTS 版本、调度器数量、消息大小、运行参数、预热次数和重复样本统计。
- [x] 为基准建立稳定的结果记录与比较规范；明确禁止把单次 wall-clock 结果作为性能结论。
- [x] 继续分析 SM2 曲线热点；此项只处理性能，标准 KDF 与密文迁移归入 P0。见 `bench/sm2_hotspot_analysis.md`（2026-08-19，`mix run bench/bench.exs` 基线 + eprof/fprof 剖析：`mod/2` 55% 为首要热点，已给出 `mod` 快速路径、窗口化、Montgomery 三级优化路径）。
- [x] 分别评估流式 SM3、SM4 CBC 和 SM4 CTR API，明确状态对象、分块规则、padding/finalize 行为及认证边界。
- [x] 调研国密证书解析与 SM9 支持，形成范围、依赖、标准与测试来源说明；当前决定暂不实现 SM9。

### P2：后续性能优化候选

以下项目不属于当前已完成的 P2 基线，必须在标准兼容性和侧信道边界明确后再实施：

- [ ] 重新执行 `eprof`/`fprof`，在固定硬件、OTP/Elixir、调度器和输入规模下记录 SM2 热点，确认 `mod/2` 优化后的新瓶颈。
- [ ] 评估固定窗口或 wNAF 标量乘法，比较生成、签名、验签和加解密收益；必须补充窗口查表的缓存侧信道风险评估，不能只按吞吐量验收。
- [ ] 评估 Montgomery 域乘法与恒定时间模逆，明确是否以侧信道加固为目标；实现前先确定中间值范围、转换边界、错误语义和公开测试向量。
- [ ] 评估批量验签的 Montgomery batch inversion，明确批量 API 的失败项定位、内存上限和调用方是否接受批量语义。
- [ ] 为 SM2 性能建立可重复的基准门禁：固定运行环境或专用 runner，至少两轮独立样本，使用 median 与置信区间，避免将单次 wall-clock 作为发布阻断依据。

后续性能优化的完成条件：

- 保持 GB/T 测试向量、负面测试和 OpenSSL 双向互操作通过。
- 同机同参 median 至少改善 10%，且 max 不恶化超过 15%；结果必须附带提交号和运行环境。
- 若引入窗口化、Montgomery 或其他时序敏感实现，必须同步更新 `SECURITY.md` 和安全审查报告。
- 第三方安全审计前，不得以性能优化结果宣称纯 Elixir 曲线运算具备恒定时间安全性。

## 完成定义

- 密码学功能必须有标准测试向量、负面测试和明确的二进制格式说明。
- 兼容性功能必须至少与一种独立实现完成双向验证，或记录无法验证的原因。
- 公开 API 变更必须同步更新模块文档、README、CLI 文档、CHANGELOG 和迁移说明。
- CI、发布或文档待办只有在对应自动化检查落地后才能标记完成。
- 安全相关功能在独立审查完成前不得宣称适合生产环境或敏感数据。

## 已完成里程碑

- [x] 纯 Elixir SM2、SM3、SM4 核心实现，不依赖 OpenSSL 国密算法支持。
- [x] SM4 ECB、CBC 与 CTR 库 API。
- [x] SM2 输入校验和确定性错误返回。
- [x] CLI 必填参数校验与显式 hex 输入/输出选项。
- [x] 跨平台 CI、GitHub Release 与 Hex 自动发布流程。
- [x] README、CLI、兼容性和安全边界文档。