Struct AeadCtx

Source

pub struct AeadCtx(/* private fields */);

Expand description

An AEAD encryption/decryption context wrapping BoringSSL’s EVP_AEAD_CTX.

Holds the keying material for a specific Algorithm. Use AeadCtx::new_default_tag for the common case, or AeadCtx::new when you need a custom tag length.

See AeadCtxRef::seal_in_place and AeadCtxRef::open_in_place for the primary encryption/decryption API.

Implementations§

Source §

impl AeadCtx

Source

pub fn new( algorithm: &Algorithm, key: &[u8], tag_len: usize, ) -> Result<Self, ErrorStack>

Creates a new AEAD context.

tag_len controls the default tag length used by the context.

This corresponds to EVP_AEAD_CTX_new.

Source

pub fn new_default_tag( algorithm: &Algorithm, key: &[u8], ) -> Result<Self, ErrorStack>

Creates a new AEAD context using the algorithm’s full (maximum) tag length.

This is the recommended constructor for most use cases. The full tag length provides the strongest authentication guarantee for the algorithm. Use AeadCtx::new instead when your protocol requires a truncated tag.

Methods from Deref<Target = AeadCtxRef>§

Source

pub fn tag_len( &self, in_len: usize, extra_in_len: usize, ) -> Result<usize, ErrorStack>

Computes the exact tag length for a seal_scatter call with the given in_len and extra_in_len.

This is useful for sizing out_tag buffers precisely rather than relying on the worst-case Algorithm::max_overhead.

This corresponds to EVP_AEAD_CTX_tag_len.

Source

pub fn seal_scatter<'a>( &self, nonce: &[u8], in_out: &mut [u8], out_tag: &'a mut [u8], extra_in: Option<&[u8]>, associated_data: &[u8], ) -> Result<&'a mut [u8], ErrorStack>

Encrypts in_out in place and writes the authentication tag to out_tag.

extra_in is optional additional plaintext for protocols that split ciphertext output across buffers. When Some(extra) is provided, the ciphertext for extra is written to the start of out_tag, followed by the detached tag bytes.

In the common case, pass None and out_tag receives only the tag.

out_tag must be large enough for all detached output: extra_in.len() + tag_len (or conservatively extra_in.len() + Algorithm::max_overhead()).

§Parameters

nonce: Per-message nonce for this encryption operation.
in_out: Plaintext input and in-place ciphertext output.
out_tag: Detached output buffer for extra_in ciphertext (if any) and the authentication tag.
extra_in: Optional extra plaintext chunk written as ciphertext into out_tag before the tag.
associated_data: Additional authenticated data (AAD).

Returns the sub-slice of out_tag that was written to. This includes any encrypted extra_in bytes and the final tag.

§Examples

use boring::aead::{AeadCtx, Algorithm};

let algorithm = Algorithm::chacha20_poly1305();
let ctx = AeadCtx::new(&algorithm, &[7u8; 32], algorithm.max_tag_len()).unwrap();

let nonce = [1u8; 12];
let aad = b"frame-header";

// Main payload is encrypted in-place.
let mut main = b"hello".to_vec();
// Extra plaintext is encrypted into the detached buffer.
let extra = b" world";
let mut detached = vec![0u8; extra.len() + algorithm.max_overhead()];

let detached_written = ctx
    .seal_scatter(
        &nonce,
        main.as_mut_slice(),
        detached.as_mut_slice(),
        Some(extra),
        aad,
    )
    .unwrap();

// `detached_written` contains: extra ciphertext bytes followed by tag bytes.
let extra_ct_len = extra.len();
let tag = &detached_written[extra_ct_len..];

// Reconstruct the full ciphertext by appending extra ciphertext bytes.
let mut full_ciphertext = main.clone();
full_ciphertext.extend_from_slice(&detached_written[..extra_ct_len]);

// `open_gather` takes ciphertext and detached tag separately.
ctx.open_gather(&nonce, full_ciphertext.as_mut_slice(), tag, aad)
    .unwrap();

assert_eq!(full_ciphertext.as_slice(), b"hello world");

This corresponds to EVP_AEAD_CTX_seal_scatter.

Source

pub fn open_gather( &self, nonce: &[u8], in_out: &mut [u8], in_tag: &[u8], associated_data: &[u8], ) -> Result<(), ErrorStack>

Decrypts in_out in place and verifies in_tag and associated_data.

When the corresponding seal_scatter call used extra_in, append the extra ciphertext prefix to in_out and pass only the tag suffix as in_tag. See the seal_scatter documentation for a full example.

§Parameters

nonce: The same nonce that was used during encryption.
in_out: Ciphertext input and in-place plaintext output.
in_tag: Detached tag bytes produced by seal_scatter.
associated_data: The same AAD that was passed during encryption.

This corresponds to EVP_AEAD_CTX_open_gather.

Source

pub fn seal_in_place<'a>( &self, nonce: &[u8], buffer: &mut [u8], tag: &'a mut [u8], associated_data: &[u8], ) -> Result<&'a mut [u8], ErrorStack>

Encrypts buffer in place and writes the authentication tag into tag.

This is a convenience wrapper around seal_scatter with extra_in = None.

§Parameters

nonce: Per-message nonce. Must match the length returned by Algorithm::nonce_len.
buffer: Plaintext on input, ciphertext on output (encrypted in place).
tag: Output buffer for the authentication tag. Must be at least Algorithm::max_overhead bytes; use AeadCtxRef::tag_len for the exact size.
associated_data: Additional authenticated data (AAD) that is authenticated but not encrypted.

Returns the sub-slice of tag that was written to.

Source