Struct VersionedFieldEncryption 

pub struct VersionedFieldEncryption { /* private fields */ }

Multi-key cipher that supports decrypting data from rotated-out keys.

Ciphertexts are prefixed with a 2-byte key version number (little-endian) so the correct key can be selected during decryption. New data is always encrypted with the primary key; old ciphertexts encrypted with a secondary/fallback key remain readable until data is migrated.

Key rotation workflow

1. Promote the new key: VersionedFieldEncryption::new(new_version, new_key_bytes)
2. Register the old key as a fallback: .with_fallback(old_version, old_key_bytes)
3. All new records are encrypted with the primary (new) key.
4. Existing records encrypted with the old key are decrypted successfully via the fallback.
5. Migrate old records by reading → decrypting → re-encrypting (see reencrypt_from_fallback).
6. Once migration is complete, remove the fallback.

Implementations

impl VersionedFieldEncryption

pub fn new( primary_version: KeyVersion, primary_key: &[u8], ) -> Result<Self, SecretsError>

Create with a single primary key.

Errors

Returns SecretsError::ValidationError if key is not 32 bytes.

pub fn with_fallback( self, version: KeyVersion, key: &[u8], ) -> Result<Self, SecretsError>

Register an additional key that can be used for decryption only.

Errors

Returns SecretsError::ValidationError if key is not 32 bytes.

pub fn encrypt(&self, plaintext: &str) -> Result<Vec<u8>, SecretsError>

Encrypt plaintext, embedding the primary key version as a 2-byte LE prefix.

Errors

Returns SecretsError::EncryptionError on failure.

pub fn extract_version(encrypted: &[u8]) -> Result<KeyVersion, SecretsError>

Extract the key version from an encrypted blob.

Errors

Returns error if encrypted is too short to contain the version prefix.

pub fn decrypt(&self, encrypted: &[u8]) -> Result<String, SecretsError>

Decrypt an encrypted blob by selecting the key matching the embedded version.

Errors

Returns SecretsError::EncryptionError if:

• The blob is too short to contain the version prefix.
• The version is unknown (not primary and not a registered fallback).
• Decryption fails (wrong key, corrupted data).

pub fn reencrypt_from_fallback( &self, old_ciphertext: &[u8], ) -> Result<Vec<u8>, SecretsError>

Re-encrypt a ciphertext from a fallback key to the current primary key.

Use this during key rotation to migrate old records without exposing the plaintext outside this function.

Errors

Returns error if decryption or re-encryption fails.