Struct ring::aead::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.
Implementations§
source§impl<N: NonceSequence> OpeningKey<N>
impl<N: NonceSequence> OpeningKey<N>
sourcepub 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]>,
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.
sourcepub 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]>,
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().