# ADR-002: Use XChaCha20-Poly1305 instead of AES-GCM

## Status
Accepted

## Context

CipherFS needs to select an authenticated encryption (AEAD) algorithm to protect user data. Main candidates:
- AES-256-GCM (industry standard)
- XChaCha20-Poly1305 (modern alternative)

Key considerations:
1. Security
2. Performance
3. Nonce management complexity
4. Cross-platform support

## Decision

**Use XChaCha20-Poly1305 as the default encryption algorithm.**

## Considered Options

### 1. AES-256-GCM

**Pros:**
- Industry standard, widely used
- Hardware acceleration (AES-NI) provides extremely high performance on supported CPUs
- NIST certified

**Cons:**
- **Nonce reuse risk**: 96-bit nonce, significant collision probability after ~2^32 random generations
- Moderate software implementation performance (without AES-NI)
- Requires careful nonce counter management

### 2. XChaCha20-Poly1305 (Selected)

**Pros:**
- **192-bit nonce**: Safe for random generation, no practical collision risk
- Efficient pure software implementation, no hardware acceleration needed
- Timing-attack resistant (constant-time implementation)
- Modern cryptographic design

**Cons:**
- No hardware acceleration (but software performance is sufficient)
- Relatively new (but widely audited)

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

**Pros:**
- Nonce reuse safe (misuse-resistant)
- 256-bit nonce

**Cons:**
- Less library support
- Slightly lower performance

## The Nonce Problem Explained

```
AES-GCM (96-bit nonce):
- Random nonce: ~50% collision probability after 2^32 encryptions
- File system scenario: 1M files × 100 modifications = 100M encryptions
- Risk: At dangerous boundary

XChaCha20-Poly1305 (192-bit nonce):
- Random nonce: collision risk only after ~2^96 encryptions
- Practically unlimited, random generation completely safe
```

## Performance Comparison

| Scenario | AES-256-GCM (AES-NI) | AES-256-GCM (Software) | XChaCha20-Poly1305 |
|----------|----------------------|------------------------|-------------------|
| Desktop CPU | ~5 GB/s | ~500 MB/s | ~2 GB/s |
| Mobile Device | ~1 GB/s | ~100 MB/s | ~500 MB/s |
| Raspberry Pi | ~200 MB/s | ~30 MB/s | ~150 MB/s |

**Conclusion**: XChaCha20 is generally superior to AES-GCM without hardware acceleration in software implementation.

## Rationale

1. **Nonce security**: File systems generate numerous encryption operations, XChaCha20's 192-bit nonce completely eliminates nonce collision risk
2. **Consistent cross-platform performance**: No dependency on hardware acceleration, predictable performance on all platforms
3. **Simplified implementation**: Random nonce requires no counter management
4. **Modern standard**: Adopted by TLS 1.3, WireGuard, Noise Protocol, etc.

## Consequences

### Pros
- Safe random nonce, no complex nonce management needed
- Consistent cross-platform performance
- Simpler code, reduced chance of errors

### Cons
- Cannot utilize AES-NI hardware acceleration
- Incompatible with some legacy systems

### Mitigation
- Support algorithm migration (Cipher trait), future algorithm switching possible
- Block-level algorithm tags, support hybrid storage

## Related Documents