# 项目分析报告：Guomi

## 📌 项目概述

**Guomi** 是一个 Elixir 语言实现的**国密算法库**，基于 Erlang/OTP `:crypto` 模块能力构建。

| 属性 | 值 |
|------|------|
| **项目名** | guomi |
| **版本** | 0.1.0 |
| **语言** | Elixir (~> 1.14) |
| **许可证** | MIT |
| **依赖** | 仅 `ex_doc`（开发文档）|

---

## 📁 项目结构

```
guomi/
├── lib/
│   ├── guomi.ex      # 主模块（外观模式，当前为空壳）
│   ├── sm2.ex        # SM2 非对称加密算法（签名/验签）
│   ├── sm3.ex        # SM3 哈希算法
│   └── sm4.ex        # SM4 对称加密算法（ECB/CBC模式）
├── test/
│   ├── sm2_test.exs  # SM2 测试（19个测试用例）
│   ├── sm3_test.exs  # SM3 测试（10个测试用例）
│   ├── sm4_test.exs  # SM4 测试（19个测试用例）
│   └── test_helper.exs
├── mix.exs           # 项目配置
└── README.md         # 中文文档
```

---

## 🔐 算法实现详情

### 1. SM3 - 哈希算法 (`lib/sm3.ex`)

| 功能 | 状态 | 说明 |
|------|------|------|
| `hash/1` | ✅ | 返回 32 字节二进制哈希 |
| `hash_hex/1` | ✅ | 返回 64 字符小写十六进制字符串 |
| `supported?/0` | ✅ | 运行时检测 SM3 可用性 |

**特点**：
- 支持 `binary()` 和 `iodata()` 输入
- 完全依赖 Erlang `:crypto.hash(:sm3, data)`

---

### 2. SM4 - 对称加密 (`lib/sm4.ex`)

| 功能 | 状态 | 说明 |
|------|------|------|
| ECB 模式 | ✅ | `encrypt/3`, `decrypt/3` |
| CBC 模式 | ✅ | `encrypt_cbc/4`, `decrypt_cbc/4` |
| PKCS7 填充 | ✅ | 默认填充方式 |
| 无填充 | ✅ | `padding: :none` |
| `supported?/0` | ✅ | 检测 SM4 可用性 |

**技术规格**：
- 密钥长度：16 字节（128位）
- 块大小：16 字节（128位）
- IV 长度：16 字节（CBC模式）

---

### 3. SM2 - 非对称加密 (`lib/sm2.ex`)

| 功能 | 状态 | 说明 |
|------|------|------|
| 密钥对生成 | ✅ | `generate_keypair/0` |
| 签名 | ✅ | `sign/2` |
| 验签 | ✅ | `verify/3` |
| 加密 | ❌ | 返回 `{:error, :unsupported}` |
| 解密 | ❌ | 返回 `{:error, :unsupported}` |
| `supported?/0` | ✅ | 检测 SM2 曲线和 SM3 支持 |

**技术规格**：
- 曲线：`:sm2`
- 私钥长度：32 字节
- 公钥长度：65 字节（未压缩格式，首字节 0x04）
- 签名长度：64 字节

---

## ✅ 测试覆盖

| 模块 | 测试数 | 覆盖率 |
|------|--------|--------|
| SM2 | 19 个 | 签名验签、边界条件、错误处理 |
| SM3 | 10 个 | 标准向量、边界条件、中文字符 |
| SM4 | 19 个 | ECB/CBC 模式、填充、大数据量 |

**测试特点**：
- 使用 `async: true` 并行执行
- 对不支持的环境优雅降级（`{:error, :unsupported}`）
- 包含官方标准测试向量

---

## 🏗️ 架构设计

```
┌─────────────────────────────────────────┐
│           Guomi (外观模块)              │
├─────────────┬─────────────┬─────────────┤
│   SM2       │    SM3      │    SM4      │
│  非对称加密  │   哈希算法   │  对称加密   │
├─────────────┴─────────────┴─────────────┤
│       Erlang/OTP :crypto 模块           │
├─────────────────────────────────────────┤
│         OpenSSL 3.0+ (底层)             │
└─────────────────────────────────────────┘
```

---

## ⚠️ 注意事项

1. **运行时依赖**：算法可用性取决于 Erlang/OTP 和 OpenSSL 版本
   - 推荐：OTP 24+ 和 OpenSSL 3.0+

2. **SM2 加密限制**：当前实现仅支持签名验签，加解密功能未实现

3. **错误处理**：所有 API 使用 `{:ok, result} | {:error, reason}` 元组返回格式

---

## 🚀 使用示例

```elixir
# SM3 哈希
Guomi.SM3.hash_hex("abc")
#=> "66c7f0f462eeedd9d1f2d46bdc10e4e24167c4875cf2f7a2297da02b8f4ba8e0"

# SM4 加密
key = Base.decode16!("0123456789ABCDEFFEDCBA9876543210", case: :mixed)
{:ok, cipher} = Guomi.SM4.encrypt("secret data", key)
{:ok, plain} = Guomi.SM4.decrypt(cipher, key)

# SM2 签名
{:ok, sk, pk} = Guomi.SM2.generate_keypair()
{:ok, sig} = Guomi.SM2.sign("message", sk)
{:ok, true} = Guomi.SM2.verify("message", sig, pk)
```

---

## 📊 代码统计

| 文件 | 行数 | 说明 |
|------|------|------|
| `lib/guomi.ex` | 5 | 空壳外观模块 |
| `lib/sm2.ex` | 85 | SM2 实现 |
| `lib/sm3.ex` | 24 | SM3 实现 |
| `lib/sm4.ex` | 149 | SM4 实现 |
| `test/sm2_test.exs` | 161 | SM2 测试 |
| `test/sm3_test.exs` | 61 | SM3 测试 |
| `test/sm4_test.exs` | 137 | SM4 测试 |

**总计**：约 622 行代码（含测试）

---

*分析报告生成时间：2026-03-23*