# ADR 004: Algorithm Agility Design

## Status

Accepted - 2025-01-09

## Context

CipherFS uses XChaCha20-Poly1305 encryption and Blake3 hashing algorithms. With the evolution of cryptography, it may become necessary to:

1. Discover weaknesses or vulnerabilities in current algorithms
2. Adopt more efficient new algorithms
3. Meet new compliance requirements (such as FIPS standards)

The current implementation hardcodes these algorithms, leading to:
- Inability to upgrade algorithms without breaking existing data
- Need for large-scale data migration to change algorithms
- Inability to interoperate between different software versions

## Decision

Implement a **versioned metadata system** that supports coexistence of multiple algorithms:

1. **Algorithm enumeration**: Define enumeration types for encryption and hash algorithms
2. **Dynamic sizing**: Use `Vec<u8>` instead of fixed-size arrays
3. **Version numbers**: Metadata includes version fields, supporting format evolution
4. **Validation**: Automatically validate algorithm-specific length requirements

## Consequences

### Positive

- ✅ **Zero-downtime migration**: New and old algorithms can coexist
- ✅ **No data migration needed**: Existing data can continue using old algorithms
- ✅ **Forward compatibility**: New algorithms can be added without breaking existing functionality
- ✅ **Flexibility**: Support on-demand file migration
- ✅ **Validation protection**: Automatically detect corrupted or malformed data

### Negative

- ⚠️ **Increased complexity**: Metadata format is more complex
- ⚠️ **Minor performance overhead**: Using `Vec<u8>` instead of fixed arrays
- ⚠️ **Testing burden**: Need to test multiple algorithm combinations
- ⚠️ **CAS limitations**: Current CAS layer still uses Blake3 (but prepared for upgrade)

### Neutral

- → **Increased metadata size**: 4 bytes per chunk (length field), but negligible for large files
- → **Code complexity**: Need to maintain code paths for multiple algorithms

## Implementation

### Core Code Locations

- `crates/cipherfs-core/src/crypto/mod.rs`: Algorithm enumeration definitions
- `crates/cipherfs-core/src/vault.rs`: Versioned metadata implementation
- `crates/cipherfs-core/src/storage/cas.rs`: CAS algorithm agility support

### Serialization Format

```
[version: 1]          - 1 byte  (metadata version)
[encryption: 1]       - 1 byte  (encryption algorithm ID)
[hash: 1]             - 1 byte  (hash algorithm ID)
[size: 8]             - 8 bytes (file size)
[chunk_count: 4]      - 4 bytes (chunk count)
For each chunk:
  [hash_len: 2]       - 2 bytes (hash length)
  [hash: N]           - N bytes (hash value)
  [nonce_len: 2]      - 2 bytes (nonce length)
  [nonce: M]          - M bytes (nonce value)
[modified: 8]         - 8 bytes (modification timestamp)
```

### Algorithm Support Matrix

| Encryption Algorithm | Nonce Length | Status |
|---------------------|-------------|--------|
| XChaCha20-Poly1305 | 24 bytes | ✅ Default |
| AES-256-GCM | 12 bytes | 🚧 Future |
| ChaCha20-Poly1305 | 12 bytes | 🚧 Future |

| Hash Algorithm | Output Length | Status |
|---------------|--------------|--------|
| Blake3 | 32 bytes | ✅ Default |
| SHA-256 | 32 bytes | 🚧 Future |
| SHA-512 | 64 bytes | 🚧 Future |

## Alternatives

### Option A: Global Algorithm Upgrade (Not Adopted)

- One-time upgrade of all files to new algorithm
- **Reason for rejection**: Requires large-scale downtime and migration

### Option B: Multiple Data Stores (Not Adopted)

- Maintain independent storage for each algorithm
- **Reason for rejection**: Increases storage and code complexity

### Option C: Algorithm Negotiation Protocol (Not Adopted)

- Client and server negotiate algorithm
- **Reason for rejection**: Over-engineered, not currently needed

## Future Work

1. **AES-256-GCM support**: Add AES-256-GCM algorithm (requires hardware acceleration detection)
2. **Automatic migration**: Background automatic migration of old files
3. **Algorithm rotation strategy**: Regular automatic rotation of encryption algorithms
4. **CAS hash upgrade**: Support CAS with different hash algorithms

## References

- [NIST Cryptographic Algorithm Guidelines](https://csrc.nist.gov/projects/lightweight-cryptography)
- [Algorithm Agility Best Practices](https://www.rfc-editor.org/rfc/rfc7696)
- [Cryptographic Algorithm Flexibility](https://www.ssi.gouv.fr/en/publication/publication-recommendation-for-the-transition-to-the-use-of-quantum-resistant-cryptography/)

## Related ADRs

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