# ADR 004: 算法敏捷性设计

## 状态

已接受 (Accepted) - 2025-01-09

## 上下文

CipherFS 使用 XChaCha20-Poly1305 加密和 Blake3 哈希算法。随着密码学的发展，可能会：

1. 发现当前算法的弱点或漏洞
2. 出现更高效的新算法
3. 需要符合新的合规要求（如 FIPS 标准）

当前实现硬编码了这些算法，导致：
- 无法升级算法而不破坏现有数据
- 需要大规模数据迁移才能更改算法
- 不同版本的软件无法互操作

## 决策

实施**版本化元数据系统**，支持多算法共存：

1. **算法枚举**: 为加密和哈希算法定义枚举类型
2. **动态大小**: 使用 `Vec<u8>` 而非固定大小数组
3. **版本号**: 元数据包含版本字段，支持格式演进
4. **验证**: 自动验证算法特定的长度要求

## 后果

### 正面

- ✅ **零停机迁移**: 新旧算法可以共存
- ✅ **无需数据迁移**: 现有数据可以继续使用旧算法
- ✅ **向前兼容**: 可以添加新算法而不破坏现有功能
- ✅ **灵活性**: 支持按需迁移文件
- ✅ **验证保护**: 自动检测损坏或格式错误的数据

### 负面

- ⚠️ **复杂度增加**: 元数据格式更复杂
- ⚠️ **轻微性能开销**: 使用 `Vec<u8>` 而非固定数组
- ⚠️ **测试负担**: 需要测试多种算法组合
- ⚠️ **CAS 限制**: 当前 CAS 层仍使用 Blake3（但已为升级做好准备）

### 中性

- → **元数据大小增加**: 每个块增加 4 字节（长度字段），但对于大文件可忽略
- → **代码复杂度**: 需要维护多个算法的代码路径

## 实现

### 核心代码位置

- `crates/cipherfs-core/src/crypto/mod.rs`: 算法枚举定义
- `crates/cipherfs-core/src/vault.rs`: 版本化元数据实现
- `crates/cipherfs-core/src/storage/cas.rs`: CAS 算法敏捷性支持

### 序列化格式

```
[version: 1]          - 1 byte  (元数据版本)
[encryption: 1]       - 1 byte  (加密算法 ID)
[hash: 1]             - 1 byte  (哈希算法 ID)
[size: 8]             - 8 bytes (文件大小)
[chunk_count: 4]      - 4 bytes (块数量)
For each chunk:
  [hash_len: 2]       - 2 bytes (哈希长度)
  [hash: N]           - N bytes (哈希值)
  [nonce_len: 2]      - 2 bytes (nonce 长度)
  [nonce: M]          - M bytes (nonce 值)
[modified: 8]         - 8 bytes (修改时间戳)
```

### 算法支持矩阵

| 加密算法 | Nonce 长度 | 状态 |
|---------|-----------|------|
| XChaCha20-Poly1305 | 24 字节 | ✅ 默认 |
| AES-256-GCM | 12 字节 | 🚧 未来 |
| ChaCha20-Poly1305 | 12 字节 | 🚧 未来 |

| 哈希算法 | 输出长度 | 状态 |
|---------|---------|------|
| Blake3 | 32 字节 | ✅ 默认 |
| SHA-256 | 32 字节 | 🚧 未来 |
| SHA-512 | 64 字节 | 🚧 未来 |

## 替代方案

### 方案 A: 全局算法升级（未采用）

- 一次性升级所有文件到新算法
- **拒绝原因**: 需要大规模停机和迁移

### 方案 B: 多个数据存储（未采用）

- 为每种算法维护独立的存储
- **拒绝原因**: 增加存储和代码复杂度

### 方案 C: 算法协商协议（未采用）

- 客户端和服务器协商算法
- **拒绝原因**: 过度设计，当前不需要

## 未来工作

1. **AES-256-GCM 支持**: 添加 AES-256-GCM 算法（需要硬件加速检测）
2. **自动迁移**: 后台自动迁移旧文件
3. **算法轮换策略**: 定期自动轮换加密算法
4. **CAS 哈希升级**: 支持不同哈希算法的 CAS

## 参考

- [NIST 密码算法指南](https://csrc.nist.gov/projects/lightweight-cryptography)
- [算法敏捷性最佳实践](https://www.rfc-editor.org/rfc/rfc7696)
- [加密算法灵活性](https://www.ssi.gouv.fr/en/publication/publication-recommendation-for-the-transition-to-the-use-of-quantum-resistant-cryptography/)

## 相关 ADR

- [ADR 001: redb](001-database-redb.zh.md)
- [ADR 002: XChaCha20-Poly1305](002-encryption-xchacha20.zh.md)
- [ADR 003: FastCDC](003-chunking-fastcdc.zh.md)