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

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
• Algorithm Agility Best Practices
• Cryptographic Algorithm Flexibility

Related ADRs

• ADR 001: redb
• ADR 002: XChaCha20-Poly1305
• ADR 003: FastCDC

Source file in the repository