Struct XChaCha20Poly1305Cipher 

pub struct XChaCha20Poly1305Cipher { /* private fields */ }

A vault-keyed XChaCha20-Poly1305 PayloadCipher with a one-key rotation window.

The cipher holds a current key used for all seals, plus an optional previous key that open can still select during a rotation window. The on-disk layout key_id(1) || nonce(24) || ciphertext || tag(16) lets open pick the right key by its leading byte; an unrecognized key-id fails closed with CipherError::UnknownKeyId.

Key rotation is otherwise drain-based: see book vault documentation for the operational policy. See zeph_durable::PayloadCipher for the full contract.

Implementations

impl XChaCha20Poly1305Cipher

pub fn new(key_id: u8, key: [u8; 32]) -> Self

Construct a cipher with a single current key identified by key_id.

The key array is zeroized once copied into the AEAD state.

pub fn from_vault_bytes(key_id: u8, key: &[u8]) -> Result<Self, CipherKeyError>

Construct a cipher from vault-resolved key bytes, validating the length.

Errors

Returns CipherKeyError::InvalidKeyLength when key is not exactly 32 bytes.

Examples

use zeph_core::durable::XChaCha20Poly1305Cipher;

assert!(XChaCha20Poly1305Cipher::from_vault_bytes(0, &[0u8; 32]).is_ok());
assert!(XChaCha20Poly1305Cipher::from_vault_bytes(0, b"too short").is_err());

pub fn from_vault_b64(b64_key: &str) -> Result<Self, CipherKeyError>

Construct the current cipher from the base64-encoded ZEPH_DURABLE_KEY vault value.

This is the single decode path shared by the agent-loop engine and the zeph durable --reveal CLI; both use DURABLE_KEY_ID so a sealed blob round-trips. The key is generated in this same encoding by generate_durable_key_b64.

Errors

Returns CipherKeyError::MalformedEncoding when b64_key is not valid base64, or CipherKeyError::InvalidKeyLength when the decoded key is not exactly 32 bytes.

Examples

use zeph_core::durable::{XChaCha20Poly1305Cipher, generate_durable_key_b64};

let key = generate_durable_key_b64();
assert!(XChaCha20Poly1305Cipher::from_vault_b64(&key).is_ok());
assert!(XChaCha20Poly1305Cipher::from_vault_b64("not base64!").is_err());

pub fn from_vault_b64_with_id( key_id: u8, b64_key: &str, ) -> Result<Self, CipherKeyError>

Construct the current cipher from a base64-encoded vault value with an explicit key_id.

Like from_vault_b64 but for an operator-controlled key_id ([durable].key_id, zeph durable rotate-key, #6447) rather than the hardcoded DURABLE_KEY_ID default — the current cipher’s decode path used by load_durable_cipher once a rotation has bumped the config’s key_id.

Errors

Returns CipherKeyError::MalformedEncoding when b64_key is not valid base64, or CipherKeyError::InvalidKeyLength when the decoded key is not exactly 32 bytes.

Examples

use zeph_core::durable::{XChaCha20Poly1305Cipher, generate_durable_key_b64};

let key = generate_durable_key_b64();
assert!(XChaCha20Poly1305Cipher::from_vault_b64_with_id(1, &key).is_ok());

pub fn with_previous(self, key_id: u8, key: [u8; 32]) -> Self

Register a previous key for the rotation window.

open will select this key for blobs whose leading key-id byte matches key_id; seal always uses the current key. Use this so in-flight executions sealed under the old key can still be replayed after a rotation.

Trait Implementations

impl PayloadCipher for XChaCha20Poly1305Cipher

fn seal( &self, plaintext: &[u8], aad: &PayloadAad, ) -> Result<Vec<u8>, CipherError>

Seal plaintext under aad, returning the stored blob (key_id || nonce || ciphertext || tag).

fn open(&self, sealed: &[u8], aad: &PayloadAad) -> Result<Vec<u8>, CipherError>

Open a blob previously produced by seal, verifying aad.