[Encryption] Encryption Key Rotation

[github-actions[bot]]

Problem

There is currently no supported way to rotate an encryption key. Key rotation is a standard security requirement in compliance frameworks (SOC 2, PCI-DSS, ISO 27001). Without it, a compromised key cannot be remediated without rebuilding the database from scratch.

Appetite

Medium batch — ~3 days

Solution

New API on BLiteEngine:

Task RotateEncryptionKeyAsync(
    IKeyProvider newKeyProvider,
    KeyRotationOptions? options = null,
    CancellationToken ct = default
);

Rotation sequence:

1. Open database with old key (read-only during rotation)
2. Call newKeyProvider.GetKeyAsync() to obtain the new master key
3. Create a new EncryptionCoordinator with the new master key
4. For each file: decrypt each page with the old subkey → encrypt with the new subkey → write to a new temporary file
5. Atomically rename new files over old ones (OS rename, atomic on same filesystem)
6. Update FileHeader salt in each new file
7. Emit audit event KeyRotation; call IKeyProvider.NotifyKeyRotationAsync

public sealed class KeyRotationOptions
{
    public bool VerifyAfterRotation { get; init; } = true;   // re-read and verify all pages
    public string? TargetDirectory { get; init; }            // null = in-place rotation
}

Rabbit Holes

• The old key must remain valid until all files are fully rotated and verified.
• If rotation fails midway, the original files must be restored — keep originals until rotation is verified.
• Never modify files in-place during rotation; always write new files and rename atomically.

No-gos

• Online key rotation (while open for writes) is out of scope.
• Changing cipher algorithm requires a migration, not a rotation.