ADR 004: 算法敏捷性设计
状态
已接受 (Accepted) - 2025-01-09
上下文
CipherFS 使用 XChaCha20-Poly1305 加密和 Blake3 哈希算法。随着密码学的发展，可能会：
- 发现当前算法的弱点或漏洞
- 出现更高效的新算法
- 需要符合新的合规要求（如 FIPS 标准）
当前实现硬编码了这些算法，导致：
- 无法升级算法而不破坏现有数据
- 需要大规模数据迁移才能更改算法
- 不同版本的软件无法互操作
决策
实施版本化元数据系统，支持多算法共存：
- 算法枚举: 为加密和哈希算法定义枚举类型
- 动态大小: 使用
Vec<u8>而非固定大小数组 - 版本号: 元数据包含版本字段，支持格式演进
- 验证: 自动验证算法特定的长度要求
后果
正面
- ✅ 零停机迁移: 新旧算法可以共存
- ✅ 无需数据迁移: 现有数据可以继续使用旧算法
- ✅ 向前兼容: 可以添加新算法而不破坏现有功能
- ✅ 灵活性: 支持按需迁移文件
- ✅ 验证保护: 自动检测损坏或格式错误的数据
负面
- ⚠️ 复杂度增加: 元数据格式更复杂
- ⚠️ 轻微性能开销: 使用
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: 算法协商协议（未采用）
- 客户端和服务器协商算法
- 拒绝原因: 过度设计，当前不需要
未来工作
- AES-256-GCM 支持: 添加 AES-256-GCM 算法（需要硬件加速检测）
- 自动迁移: 后台自动迁移旧文件
- 算法轮换策略: 定期自动轮换加密算法
- CAS 哈希升级: 支持不同哈希算法的 CAS