Struct ring::aead::OpeningKey

pub struct OpeningKey<N: NonceSequence> { /* private fields */ }

An AEAD key for authenticating and decrypting (“opening”), bound to a nonce sequence.

Intentionally not Clone or Copy since cloning would allow duplication of the nonce sequence.

Implementations

impl<N: NonceSequence> OpeningKey<N>

pub fn open_in_place<'in_out, A>(
    &mut self,
    aad: Aad<A>,
    in_out: &'in_out mut [u8]
) -> Result<&'in_out mut [u8], Unspecified>where
    A: AsRef<[u8]>,

Authenticates and decrypts (“opens”) data in place.

aad is the additional authenticated data (AAD), if any.

On input, in_out must be the ciphertext followed by the tag. When open_in_place() returns Ok(plaintext), the input ciphertext has been overwritten by the plaintext; plaintext will refer to the plaintext without the tag.

When open_in_place() returns Err(..), in_out may have been overwritten in an unspecified way.

pub fn open_within<'in_out, A>(
    &mut self,
    aad: Aad<A>,
    in_out: &'in_out mut [u8],
    ciphertext_and_tag: RangeFrom<usize>
) -> Result<&'in_out mut [u8], Unspecified>where
    A: AsRef<[u8]>,

Authenticates and decrypts (“opens”) data in place, with a shift.

aad is the additional authenticated data (AAD), if any.

On input, in_out[ciphertext_and_tag] must be the ciphertext followed by the tag. When open_within() returns Ok(plaintext), the plaintext will be at in_out[0..plaintext.len()]. In other words, the following two code fragments are equivalent for valid values of ciphertext_and_tag, except open_within will often be more efficient:

let plaintext = key.open_within(aad, in_out, cipertext_and_tag)?;

let ciphertext_and_tag_len = in_out[ciphertext_and_tag].len();
in_out.copy_within(ciphertext_and_tag, 0);
let plaintext = key.open_in_place(aad, &mut in_out[..ciphertext_and_tag_len])?;

Similarly, key.open_within(aad, in_out, 0..) is equivalent to key.open_in_place(aad, in_out).

When open_in_place() returns Err(..), in_out may have been overwritten in an unspecified way.

The shifting feature is useful in the case where multiple packets are being reassembled in place. Consider this example where the peer has sent the message “Split stream reassembled in place” split into three sealed packets:

                Packet 1                  Packet 2                 Packet 3
Input:  [Header][Ciphertext][Tag][Header][Ciphertext][Tag][Header][Ciphertext][Tag]
                     |         +--------------+                        |
              +------+   +-----+    +----------------------------------+
              v          v          v
Output: [Plaintext][Plaintext][Plaintext]
       “Split stream reassembled in place”

This reassembly be accomplished with three calls to open_within().

Trait Implementations

impl<N: NonceSequence> BoundKey<N> for OpeningKey<N>

fn new(key: UnboundKey, nonce_sequence: N) -> Self

Constructs a new key from the given UnboundKey and NonceSequence.

fn algorithm(&self) -> &'static Algorithm

The key’s AEAD algorithm.

impl<N: NonceSequence> Debug for OpeningKey<N>

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.