Struct OpeningKey

Source

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

Expand description

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.

Prefer RandomizedNonceKey for opening operations.

Implementations§

Source §

impl<N: NonceSequence> OpeningKey<N>

Source

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.

Prefer RandomizedNonceKey::open_in_place.

§Errors

error::Unspecified when ciphertext is invalid. In this case, in_out may have been overwritten in an unspecified way.

Source

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).

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().

Prefer RandomizedNonceKey::open_in_place.

§Errors

error::Unspecified when ciphertext is invalid. In this case, in_out may have been overwritten in an unspecified way.

Source

pub fn prepare_nonce( &mut self, ) -> Result<OpeningKeyPreparedNonce<'_, N>, Unspecified>

Returns a OpeningKeyPreparedNonce containing the next computed Nonce consumed from NonceSequence.

The encapsulated Nonce will be used if and only if either OpeningKeyPreparedNonce::open_in_place or OpeningKeyPreparedNonce::open_within are invoked. Dropping OpeningKeyPreparedNonce without invoking either method results in the nonce remaining consumed and unused within the associated NonceSequence. Subsequent calls to OpeningKey methods will always use a proceeding nonce from the NonceSequence regardless of whether a OpeningKeyPreparedNonce is consumed or not.