Struct AeadCtxRef

Source

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

Expand description

A borrowed reference to a AeadCtx.

Implementations§

Source §

impl 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