Struct Crypt

Source

pub struct Crypt { /* private fields */ }

Available on crate features aead-chacha20 or aead-aes-gcm only.

Expand description

High-level encryption handle.

Crypt is cheap to construct and to clone — it carries only the algorithm choice, not any key material. Keys are passed per-call to encrypt and decrypt, and never stored inside Crypt itself.

§Defaults

Crypt::new() returns a handle configured for Algorithm::ChaCha20Poly1305. Use Crypt::with_algorithm to pick a different algorithm.

Implementations§

Source §

impl Crypt

Source

pub const fn new() -> Self

Construct a Crypt with the default algorithm (Algorithm::ChaCha20Poly1305).

Source

pub const fn with_algorithm(algorithm: Algorithm) -> Self

Construct a Crypt with an explicit algorithm.

Source

pub const fn aes_256_gcm() -> Self

Available on crate feature aead-aes-gcm only.

Convenience constructor for Algorithm::Aes256Gcm. Available only when the aead-aes-gcm Cargo feature is enabled.

Equivalent to Crypt::with_algorithm(Algorithm::Aes256Gcm). Provided because picking AES-GCM is an explicit, deliberate choice — usually driven by an interop requirement or by a target platform with AES-NI / ARMv8 crypto extensions — and the call site reads cleaner when it says so.

Source

pub const fn algorithm(&self) -> Algorithm

The algorithm this handle is configured to use.

Source

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

Encrypt plaintext under key and return nonce || ciphertext || tag.

A fresh 12-byte nonce is generated for every call via OS-backed CSPRNG (mod_rand::tier3::fill_bytes). The nonce is prepended to the returned buffer so the corresponding decrypt call needs only the key and the buffer.

§Errors

Error::InvalidKey if key is not 32 bytes.
Error::RandomFailure if the OS random source could not produce a nonce.
Error::AlgorithmNotEnabled if the algorithm was disabled at compile time (a feature-flag gate).

§Example

use crypt_io::Crypt;
let crypt = Crypt::new();
let key = [0u8; 32];
let ciphertext = crypt.encrypt(&key, b"hello").expect("encrypt");
assert!(ciphertext.len() > 5);

Source

pub fn encrypt_with_aad( &self, key: &[u8], plaintext: &[u8], aad: &[u8], ) -> Result<Vec<u8>>

Encrypt plaintext under key with additional authenticated data.

aad is authenticated alongside the ciphertext but is not encrypted and is not included in the returned buffer. Callers must supply identical aad to decrypt_with_aad — otherwise authentication will fail.

Pass &[] for aad to encrypt without associated data, or call the convenience method encrypt which does so.

§Errors

Same as encrypt.

Source

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

Decrypt a buffer produced by encrypt and return the plaintext.

The buffer is expected to be nonce || ciphertext || tag — exactly the layout encrypt returns. The tag is verified in constant time; any tampering, wrong key, or wrong length results in Error::AuthenticationFailed.

The returned Vec<u8> does not auto-zeroize. Callers handling long-lived keys should move the bytes into a Zeroizing<Vec<u8>> (zeroize crate) or — for production use cases — keep the plaintext in a key-vault handle and never let it touch a raw Vec.

§Errors

Error::InvalidKey if key is not 32 bytes.
Error::InvalidCiphertext if the buffer is too short to contain a nonce + tag.
Error::AuthenticationFailed for any cryptographic failure — wrong key, tampered ciphertext, or wrong associated data.
Error::AlgorithmNotEnabled if the algorithm was disabled at compile time.

§Example

use crypt_io::Crypt;
let crypt = Crypt::new();
let key = [0u8; 32];
let ciphertext = crypt.encrypt(&key, b"hello").expect("encrypt");
let recovered = crypt.decrypt(&key, &ciphertext).expect("decrypt");
assert_eq!(&*recovered, b"hello");

Source

pub fn decrypt_with_aad( &self, key: &[u8], ciphertext: &[u8], aad: &[u8], ) -> Result<Vec<u8>>

Decrypt with associated data. aad must match what was passed to encrypt_with_aad.

§Errors

Same as decrypt.

Source

pub fn encrypt_into( &self, key: &[u8], plaintext: &[u8], out: &mut Vec<u8>, ) -> Result<()>

Zero-allocation encrypt — writes nonce || ciphertext || tag into the caller-supplied out buffer. The buffer is cleared first and then grown as needed. Reusing the same buffer across calls amortises the allocation cost away entirely.

Equivalent to encrypt but does not allocate a fresh Vec per call. New in 0.10.0.

§Errors

Same as encrypt.

§Example

use crypt_io::Crypt;
let crypt = Crypt::new();
let key = [0u8; 32];
let mut out = Vec::new();

// First call grows `out` to capacity.
crypt.encrypt_into(&key, b"hello", &mut out)?;

// Subsequent calls reuse the capacity — no allocation.
crypt.encrypt_into(&key, b"world", &mut out)?;

Source

pub fn encrypt_with_aad_into( &self, key: &[u8], plaintext: &[u8], aad: &[u8], out: &mut Vec<u8>, ) -> Result<()>

Zero-allocation encrypt with associated data. See encrypt_into.

§Errors

Same as encrypt.

Source

pub fn decrypt_into( &self, key: &[u8], ciphertext: &[u8], out: &mut Vec<u8>, ) -> Result<()>

Zero-allocation decrypt — writes the recovered plaintext into the caller-supplied out buffer. The buffer is cleared first and then grown as needed.

On authentication failure the buffer is cleared (any partially-decrypted bytes are scrubbed before returning) so callers can’t accidentally observe unverified plaintext.

Equivalent to decrypt but does not allocate a fresh Vec per call. New in 0.10.0.

§Errors

Same as decrypt.

§Example

use crypt_io::Crypt;
let crypt = Crypt::new();
let key = [0u8; 32];

let mut ciphertext = Vec::new();
crypt.encrypt_into(&key, b"hello", &mut ciphertext)?;

let mut plaintext = Vec::new();
crypt.decrypt_into(&key, &ciphertext, &mut plaintext)?;
assert_eq!(&plaintext[..], b"hello");