Struct ScopedCipher 

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

A Scoped Cipher is one which has been initialized for a specific keyset. It can be used only to encrypt and decrypt data for that keyset.

Lifetime

Initialise once per process and hold an Arc<ScopedCipher<_>> for the process lifetime. Recreating a ScopedCipher on a periodic schedule (e.g. “refresh every N rows” in a bulk-ingest loop) is an anti-pattern:

• ScopedCipher carries no TTL of its own — it’s a thin wrapper around the keyset’s index key plus an Arc to the underlying ZeroKMS client. The “scope” refers to the keyset binding, not a session lifetime.
• Auth tokens used by the underlying client auto-refresh through stack_auth::AutoRefresh — preemptively, 90 s before expiry, with in-flight refreshes shared across concurrent callers via a mutex. Recreating ScopedCipher doesn’t trigger or improve this; it only discards the cached token and forces an immediate re-auth.
• Recreating the cipher discards the warm reqwest::Client connection pool. The next call after re-init pays a cold-start tax (DNS + TCP + TLS handshake) that can blow past the request timeout under variable network conditions.

If you’re working around symptoms that look like session expiry, check the actual error chain — auth errors surface as zerokms::Error::Auth, not as ZeroKMS error 'Unexpected error'. The latter is almost always a transport-level timeout (SendRequest) that periodic re-init makes worse, not better.

See the “Tuning for bulk ingest” section on ZeroKMSBuilder for the timeout / pool / batch knobs that do help long-running encrypt loops.

Implementations

impl<C> ScopedCipher<C>

pub async fn init_default( client: Arc<ZeroKMSWithClientKey<C>>, ) -> Result<Self, Error>

where C: AuthStrategyBounds, for<'b> &'b C: AuthStrategy,

Initialize a new ScopedCipher for the default keyset_id.

pub async fn init( client: Arc<ZeroKMSWithClientKey<C>>, keyset_id: Option<IdentifiedBy>, ) -> Result<Self, Error>

where C: AuthStrategyBounds, for<'b> &'b C: AuthStrategy,

Initialize a new ScopedCipher for the given keyset_id. If the keyset_id is None, the ScopedCipher will be initialized with the default keyset_id for the client.

pub fn mac<const N: usize>(&self, value: &str, prefix: Option<&str>) -> [u8; N]

This value is used for term index keys and “encrypted” partition / sort keys

pub fn compound_index<I>( &self, index: I, plaintext: ComposablePlaintext, info: String, ) -> Result<IndexTerm, EncryptionError>

where I: ComposableIndex + Send,

pub fn compound_query<I>( &self, index: I, input: ComposablePlaintext, info: String, ) -> Result<IndexTerm, EncryptionError>

where I: ComposableIndex + Send,

pub async fn encrypt( &self, payloads: impl IntoIterator<Item = EncryptPayload<'_>>, ) -> Result<Vec<EncryptedRecord>, Error>

where C: AuthStrategyBounds, for<'b> &'b C: AuthStrategy,

Encrypt a stream of EncryptPayload and return them as an EncryptedRecord. This function wraps the ZeroKMSWithClientKey::encrypt function but with the keyset_id set.

pub async fn decrypt<'a, D>( &self, payloads: impl IntoIterator<Item = D>, opts: &DecryptOptions<'a>, ) -> Result<Vec<Vec<u8>>, Error>

where D: Decryptable, C: AuthStrategyBounds, for<'b> &'b C: AuthStrategy,

Decrypt a stream of encrypted values (of type D where D: Decryptable) and return the raw decrypted binary blob.

pub async fn decrypt_fallible<'a, D>( &self, payloads: impl IntoIterator<Item = D>, opts: &DecryptOptions<'a>, ) -> Result<Vec<Result<Vec<u8>, RecordDecryptError>>, Error>

where D: Decryptable, C: AuthStrategyBounds, for<'b> &'b C: AuthStrategy,

pub fn index_key(&self) -> &IndexKey

pub fn keyset_id(&self) -> Uuid

Trait Implementations

impl<C> Debug for ScopedCipher<C>

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

Formats the value using the given formatter.

impl<C> Drop for ScopedCipher<C>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl<C> Zeroize for ScopedCipher<C>

fn zeroize(&mut self)

Zero out this object from memory using Rust intrinsics which ensure the zeroization operation is not “optimized away” by the compiler.