Struct RefreshableCipher 

pub struct RefreshableCipher<C> { /* private fields */ }

An AEAD cipher that holds a hot-swappable inner cipher behind an ArcSwap.

This is the pure mechanism layer — it knows how to atomically swap the inner cipher by re-invoking a factory closure. Concurrent refresh attempts are serialised so that only one factory call runs at a time; waiters that arrive while a refresh is in flight adopt the result.

Policy concerns (TTL, failure backoff) are handled by ScheduledRefreshCipher, which wraps the same mechanism.

This allows runtime rotation of encryption keys (e.g. from a KMS or secret manager) without restarting the application.

For emitting, go through the selector API (select_cipher / select_sealer), which hands back a frozen snapshot. Using the type directly as an AeadEncryptor takes a fresh snapshot per call, so reading metadata and then encrypting can straddle a rotation — the hazard the selector exists to prevent (see composing crypto strategies); the bare impl exists only for composition and erasure.

All clones share the same underlying state, so a refresh performed through any clone is visible to all others — a single RefreshableCipher can be cloned into a sealer and an unsealer while one handle is kept for refresh.

Implementations

impl<C: Debug + MaybeSendSync + 'static> RefreshableCipher<C>

pub async fn refresh(&self) -> Result<bool, Error>

Refreshes the cipher by re-invoking the factory and atomically swapping the inner value.

Concurrent callers are serialised — only one factory call runs at a time. If another task already refreshed while this one was waiting for the lock, the new value is adopted without a redundant fetch.

Returns Ok(true) if new key material was fetched by this call, or Ok(false) if another task already refreshed concurrently.

Errors

Returns an error if the factory call fails.

pub fn builder<I1>() -> RefreshableCipherBuilder<C, I1>

where I1: Fn() -> Pin<Box<dyn MaybeSendFuture<Output = Result<C, Error>>>> + MaybeSendSync + 'static,

Creates a new RefreshableCipher using the given factory.

The factory is called immediately to produce the initial cipher. The same factory is called on subsequent refreshes via refresh.

Errors

Returns an error if the initial factory call fails.

Trait Implementations

impl<C: AeadEncryptor + 'static> AeadCipherSelector for RefreshableCipher<C>

fn select_cipher(&self) -> MaybeSendBoxFuture<'_, Arc<dyn AeadEncryptor>>

Selects the current encryptor to use for encryption, refreshing stale key material first where the implementation supports it.

impl<C: AeadDecryptor + 'static> AeadDecryptor for RefreshableCipher<C>

fn cipher_match(&self, m: &CipherMatch<'_>) -> Option<KeyMatchStrength>

Returns how well this decryptor matches the given selection criteria.

fn decrypt<'a>( &'a self, cipher_match: Option<&'a CipherMatch<'a>>, nonce: &'a [u8], ciphertext: &'a [u8], tag: &'a [u8], aad: &'a [u8], ) -> MaybeSendBoxFuture<'a, Result<Vec<u8>, DecryptError>>

Asynchronously decrypts the given ciphertext with the provided nonce, tag, and associated data.

fn try_refresh(&self) -> MaybeSendBoxFuture<'_, bool>

Requests a best-effort refresh of the decryptor’s key material — the cipher analogue of JwsVerifier::try_refresh.

impl<C: AeadEncryptor + 'static> AeadEncryptor for RefreshableCipher<C>

fn enc_algorithm(&self) -> Cow<'_, str>

Returns the content encryption algorithm identifier (e.g. A256GCM).

fn key_id(&self) -> Option<Cow<'_, str>>

Returns the key ID for this encryptor, if any.

fn encrypt<'a>( &'a self, plaintext: &'a [u8], aad: &'a [u8], ) -> MaybeSendBoxFuture<'a, Result<AeadOutput, Error>>

Asynchronously encrypts the given plaintext with the associated data.

impl<C: AeadEncryptor + 'static> AeadSealerSelector for RefreshableCipher<C>

fn select_sealer(&self) -> MaybeSendBoxFuture<'_, Arc<dyn AeadSealer>>

Selects the current sealer — a frozen key snapshot — refreshing stale key material first where the implementation supports it.

impl<C: AeadDecryptor + 'static> AeadUnsealer for RefreshableCipher<C>

fn unseal<'a>( &'a self, cipher_match: Option<&'a CipherMatch<'a>>, bundle: &'a [u8], aad: &'a [u8], ) -> MaybeSendBoxFuture<'a, Result<Vec<u8>, DecryptError>>

Decrypts a versioned bundle produced by AeadSealer::seal.

impl<C> Clone for RefreshableCipher<C>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<C: Debug> Debug for RefreshableCipher<C>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.