guomi

# Future API and Algorithm Scope

本文记录流式 API、国密证书与 SM9 的调研结论。它定义是否进入实现的前置条件，不承诺具体发布时间。

## 流式 SM3/SM4

### SM3

建议后续提供显式状态对象：

```elixir
state = Guomi.SM3.init()
state = Guomi.SM3.update(state, chunk)
digest = Guomi.SM3.final(state)
```

状态需要保存 8 个链变量、未满 64 字节的尾部缓冲区和累计字节数。`final/1` 只能执行一次；累计长度溢出 SM3 的 64 位 bit-length 字段时必须返回错误。实现应使用标准分块向量验证任意切分与一次性 `hash/1` 等价。

### SM4 CTR

CTR 流状态需要保存展开后的轮密钥、下一个 128 位大端 counter，以及上一个 keystream block 尚未消费的字节。仅保存 counter 会导致非 16 字节边界切分时输出错误。`final/1` 不添加数据。

初始化必须要求显式 16 字节 counter，并继续强调同一 key/counter 组合不得复用。流式 CTR 仍不提供完整性。

### SM4 CBC

CBC 加密状态需要保存上一密文块和不足 16 字节的明文；`final/1` 根据显式 padding 策略输出最后一块。CBC 解密必须保留至少最后一个完整密文块，直到 `final/1` 才能验证并移除 PKCS#7 padding。

流式解密不得在 `final/1` 成功前把消息标记为可信。由于 CBC 本身不认证，面向不可信输入的高层接口不应鼓励调用方在完整性验证前消费流出的明文。

### 进入实现的条件

- 先决定状态结构是公开 struct 还是不透明值，以及重复 `final`、空 chunk、错误后继续调用的语义。
- 为 0、1、15、16、17 字节和大消息建立所有切分位置的等价性测试。
- 明确状态是否包含密钥材料，以及日志、Inspect 和进程消息复制的风险。
- 不把流式裸 CBC/CTR 描述成认证加密。

## 国密证书解析

第一阶段如进入实现，只考虑 DER/PEM X.509 的只读解析和 SM2 公钥提取，不自行实现证书链验证。需要覆盖：

- SubjectPublicKeyInfo 中的 SM2 曲线/算法 OID 和未压缩公钥点。
- `sm2sig_sm3` 签名算法标识、DER `r/s` 与本库 raw `r || s` 的显式转换。
- Key Usage、Extended Key Usage、Basic Constraints、Subject Alternative Name 等常用扩展的结构化读取。
- RFC 5280 的通用 X.509 语义，以及 RFC 8998 对 TLS 1.3 ShangMi 证书使用的附加约束。

链构建、名称约束、撤销、策略处理和时间验证应委托成熟 PKIX 实现。OTP 24 到当前版本对 SM2 OID/曲线支持差异必须先形成兼容矩阵，不能假设 `:public_key` 在所有声明版本上行为一致。

进入实现前需要收集：公开正向证书链、未知关键扩展、错误 OID、错误曲线点、签名不匹配、过期/未生效及交叉签发样本。

## SM9

截至 2026 年 8 月，范围依据包括：

- GB/T 38635.1-2020《SM9 标识密码算法 第1部分：总则》。
- GB/T 38635.2-2020《SM9 标识密码算法 第2部分：算法》。
- GB/T 41389-2022《SM9 密码算法使用规范》。
- GB/T 47471-2026《SM9 密码算法加密签名消息格式》，已发布并将于 2026-11-01 实施。

SM9 需要有限域扩域、双线性对、群成员检查、主密钥/用户私钥派生、签名、加密和密钥交换，规模远超在现有 SM2 曲线模块上增加一个算法。当前结论是暂不进入实现。

重新评估 SM9 实现必须同时满足：

- 明确首个交付范围（建议只选签名或只选加密，不能一次覆盖全部协议）。
- 获得可引用的官方向量、消息格式样本和至少一种独立实现互操作环境。
- 先设计扩域和配对层的常量时间、内存上限、点/群验证与 fuzz 测试策略。
- 评估采用成熟原生库与纯 Elixir 实现的安全、可移植性和维护成本。
- 预留独立密码学审查预算；在此之前不得声明生产适用。

官方标准目录：<https://openstd.samr.gov.cn/bzgk/std/std_list?p.p2=SM9>