# ADR-002: 使用 XChaCha20-Poly1305 替代 AES-GCM

## 状态
已采纳

## 背景

CipherFS 需要选择一种认证加密（AEAD）算法来保护用户数据。主要候选：
- AES-256-GCM（行业标准）
- XChaCha20-Poly1305（现代替代方案）

关键考虑因素：
1. 安全性
2. 性能
3. Nonce 管理复杂度
4. 跨平台支持

## 决策

**使用 XChaCha20-Poly1305 作为默认加密算法。**

## 考虑的选项

### 1. AES-256-GCM

**优点：**
- 行业标准，广泛使用
- 硬件加速（AES-NI）在支持的 CPU 上性能极高
- NIST 认证

**缺点：**
- **Nonce 重用风险**：96-bit nonce，随机生成约 2^32 次后碰撞概率显著
- 软件实现性能一般（无 AES-NI 时）
- 需要仔细管理 nonce 计数器

### 2. XChaCha20-Poly1305（选中）

**优点：**
- **192-bit nonce**：随机生成安全，无实际碰撞风险
- 纯软件实现高效，无需硬件加速
- 抗时序攻击（常数时间实现）
- 现代密码学设计

**缺点：**
- 无硬件加速（但软件性能已足够）
- 相对较新（但已广泛审计）

### 3. AES-256-GCM-SIV

**优点：**
- Nonce 重用安全（misuse-resistant）
- 256-bit nonce

**缺点：**
- 库支持较少
- 性能略低

## Nonce 问题详解

```
AES-GCM (96-bit nonce)：
- 随机 nonce：约 2^32 次加密后碰撞概率 50%
- 文件系统场景：100 万文件 × 100 次修改 = 1 亿次加密
- 风险：处于危险边界

XChaCha20-Poly1305 (192-bit nonce)：
- 随机 nonce：约 2^96 次加密才有碰撞风险
- 实际无限制，随机生成完全安全
```

## 性能对比

| 场景 | AES-256-GCM (AES-NI) | AES-256-GCM (软件) | XChaCha20-Poly1305 |
|------|----------------------|-------------------|-------------------|
| 桌面 CPU | ~5 GB/s | ~500 MB/s | ~2 GB/s |
| 移动设备 | ~1 GB/s | ~100 MB/s | ~500 MB/s |
| 树莓派 | ~200 MB/s | ~30 MB/s | ~150 MB/s |

**结论**：XChaCha20 在软件实现上普遍优于无硬件加速的 AES-GCM。

## 理由

1. **Nonce 安全**：文件系统会产生大量加密操作，XChaCha20 的 192-bit nonce 彻底消除 nonce 碰撞风险
2. **跨平台性能一致**：不依赖硬件加速，在所有平台上性能可预测
3. **简化实现**：随机 nonce 无需计数器管理
4. **现代标准**：被 TLS 1.3、WireGuard、Noise Protocol 等采用

## 后果

### 优点
- 随机 nonce 安全，无需复杂的 nonce 管理
- 跨平台性能一致
- 代码更简单，减少出错机会

### 缺点
- 无法利用 AES-NI 硬件加速
- 与某些传统系统不兼容

### 缓解措施
- 支持算法迁移（Cipher trait），未来可切换算法
- 块级算法标记，支持混合存储

## 相关文档