Struct XChaCha20Poly1305Cipher 

pub struct XChaCha20Poly1305Cipher { /* private fields */ }

Available on crate feature encryption only.

XChaCha20-Poly1305 cipher with a random 24-byte nonce prepended to each ciphertext.

The on-disk payload format is: [24-byte nonce][ciphertext + 16-byte Poly1305 tag].

Why XChaCha20 over AES-GCM for new buffers

• No 2³²-message limit per key. AES-GCM’s 12-byte nonce collides after ~2³² messages under the same key (a collision breaks confidentiality). XChaCha20’s 24-byte nonce makes random-nonce collision negligible well past 2⁴⁸ messages.
• Constant-time on hosts without AES-NI. ChaCha20 is constant-time in software; AES-GCM relies on hardware acceleration (AES-NI on x86, ARMv8 Crypto Extensions on aarch64) for performance and leaks timing on hosts without it (older CPUs, some embedded ARM).

Legacy AES-GCM segments still decrypt through AesGcmCipher; the two formats are byte-distinguishable only by which cipher the buffer was opened with (no envelope marker for the cipher type today — see the envelope v2 design doc for the migration path).

Implementations

impl XChaCha20Poly1305Cipher

pub fn new(key_bytes: &[u8; 32]) -> Self

Create a new cipher from a 32-byte key.

Example

use segment_buffer::{SegmentCipher, XChaCha20Poly1305Cipher};

let cipher = XChaCha20Poly1305Cipher::new(&[0u8; 32]);
let ciphertext = cipher.encrypt(b"hello").unwrap();
let plaintext = cipher.decrypt(&ciphertext).unwrap();
assert_eq!(plaintext, b"hello");

Panics

Never in practice — a 32-byte key is always valid for XChaCha20-Poly1305. The internal .expect() is a defense-in-depth assertion against a future logic bug (e.g. a key-type change); callers passing a correctly-sized key will never hit it.

pub fn from_slice(key_bytes: &[u8]) -> Result<Self, CipherError>

Create a new cipher from a 32-byte slice. Falls back to CipherError when the slice is not exactly 32 bytes.

Errors

Returns CipherError if the key length is not 32 bytes.

Trait Implementations

impl SegmentCipher for XChaCha20Poly1305Cipher

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

Encrypt plaintext, returning self-describing ciphertext.

fn decrypt(&self, ciphertext: &[u8]) -> Result<Vec<u8>, CipherError>

Decrypt previously-produced ciphertext back to the original plaintext.