# Roadmap

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

当前 P0/P1 实现与自动化验证均已完成。尚未完成的工作只有独立安全审查和 SM2 曲线热点的进一步性能分析；完成项保留在本文中作为验收记录。

## 优先级说明

- **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 仅提供机密性。
- [ ] 对公开 API、密钥与随机数处理、错误行为和时间侧信道开展独立安全审查。
- [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；外部实现不可用时明确报告原因。

## 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 结果作为性能结论。
- [ ] 继续分析 SM2 曲线运算热点；此项只处理性能，标准 KDF 与密文迁移归入 P0。
- [x] 分别评估流式 SM3、SM4 CBC 和 SM4 CTR API，明确状态对象、分块规则、padding/finalize 行为及认证边界。
- [x] 调研国密证书解析与 SM9 支持，形成范围、依赖、标准与测试来源说明；当前决定暂不实现 SM9。

## 完成定义

- 密码学功能必须有标准测试向量、负面测试和明确的二进制格式说明。
- 兼容性功能必须至少与一种独立实现完成双向验证，或记录无法验证的原因。
- 公开 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、兼容性和安全边界文档。