diff --git a/aead/src/lib.rs b/aead/src/lib.rs index f19290a1..e72170ba 100644 --- a/aead/src/lib.rs +++ b/aead/src/lib.rs @@ -62,19 +62,29 @@ macro_rules! impl_decrypt_in_place { let tag_pos = $buffer.len() - Self::TagSize::to_usize(); let (msg, tag) = $buffer.as_mut().split_at_mut(tag_pos); - $aead.decrypt_in_place_detached($nonce, $aad, msg, GenericArray::from_slice(tag))?; + $aead.decrypt_in_place_detached($nonce, $aad, msg, Tag::from_slice(tag))?; $buffer.truncate(tag_pos); Ok(()) }}; } +/// Key for a [`NewAead`] algorithm +// TODO(tarcieri): make this a struct and zeroize on drop? +pub type Key = GenericArray::KeySize>; + +/// Nonce: single-use value for ensuring ciphertexts are unique +pub type Nonce = GenericArray; + +/// Tag: authentication code which ensures ciphertexts are authentic +pub type Tag = GenericArray; + /// Instantiate either a stateless [`Aead`] or stateful [`AeadMut`] algorithm. pub trait NewAead { /// The size of the key array required by this algorithm. type KeySize: ArrayLength; /// Construct a new stateful instance for the given key. - fn new(key: &GenericArray) -> Self; + fn new(key: &Key) -> Self; } /// Authenticated Encryption with Associated Data (AEAD) algorithm. @@ -84,8 +94,10 @@ pub trait NewAead { pub trait Aead { /// The length of a nonce. type NonceSize: ArrayLength; + /// The maximum length of the nonce. type TagSize: ArrayLength; + /// The upper bound amount of additional space required to support a /// ciphertext vs. a plaintext. type CiphertextOverhead: ArrayLength + Unsigned; @@ -117,7 +129,7 @@ pub trait Aead { #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))] fn encrypt<'msg, 'aad>( &self, - nonce: &GenericArray, + nonce: &Nonce, plaintext: impl Into>, ) -> Result, Error> { let payload = plaintext.into(); @@ -138,7 +150,7 @@ pub trait Aead { /// resulting ciphertext message. fn encrypt_in_place( &self, - nonce: &GenericArray, + nonce: &Nonce, associated_data: &[u8], buffer: &mut impl Buffer, ) -> Result<(), Error> { @@ -150,10 +162,10 @@ pub trait Aead { /// Encrypt the data in-place, returning the authentication tag fn encrypt_in_place_detached( &self, - nonce: &GenericArray, + nonce: &Nonce, associated_data: &[u8], buffer: &mut [u8], - ) -> Result, Error>; + ) -> Result, Error>; /// Decrypt the given ciphertext slice, and return the resulting plaintext /// as a vector of bytes. @@ -176,7 +188,7 @@ pub trait Aead { #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))] fn decrypt<'msg, 'aad>( &self, - nonce: &GenericArray, + nonce: &Nonce, ciphertext: impl Into>, ) -> Result, Error> { let payload = ciphertext.into(); @@ -192,7 +204,7 @@ pub trait Aead { /// message upon success. fn decrypt_in_place( &self, - nonce: &GenericArray, + nonce: &Nonce, associated_data: &[u8], buffer: &mut impl Buffer, ) -> Result<(), Error> { @@ -204,10 +216,10 @@ pub trait Aead { /// is modified/unauthentic) fn decrypt_in_place_detached( &self, - nonce: &GenericArray, + nonce: &Nonce, associated_data: &[u8], buffer: &mut [u8], - tag: &GenericArray, + tag: &Tag, ) -> Result<(), Error>; } @@ -215,8 +227,10 @@ pub trait Aead { pub trait AeadMut { /// The length of a nonce. type NonceSize: ArrayLength; + /// The maximum length of the nonce. type TagSize: ArrayLength; + /// The upper bound amount of additional space required to support a /// ciphertext vs. a plaintext. type CiphertextOverhead: ArrayLength + Unsigned; @@ -230,7 +244,7 @@ pub trait AeadMut { #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))] fn encrypt<'msg, 'aad>( &mut self, - nonce: &GenericArray, + nonce: &Nonce, plaintext: impl Into>, ) -> Result, Error> { let payload = plaintext.into(); @@ -251,7 +265,7 @@ pub trait AeadMut { /// resulting ciphertext message. fn encrypt_in_place( &mut self, - nonce: &GenericArray, + nonce: &Nonce, associated_data: &[u8], buffer: &mut impl Buffer, ) -> Result<(), Error> { @@ -263,10 +277,10 @@ pub trait AeadMut { /// Encrypt the data in-place, returning the authentication tag fn encrypt_in_place_detached( &mut self, - nonce: &GenericArray, + nonce: &Nonce, associated_data: &[u8], buffer: &mut [u8], - ) -> Result, Error>; + ) -> Result, Error>; /// Decrypt the given ciphertext slice, and return the resulting plaintext /// as a vector of bytes. @@ -277,7 +291,7 @@ pub trait AeadMut { #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))] fn decrypt<'msg, 'aad>( &mut self, - nonce: &GenericArray, + nonce: &Nonce, ciphertext: impl Into>, ) -> Result, Error> { let payload = ciphertext.into(); @@ -293,7 +307,7 @@ pub trait AeadMut { /// message upon success. fn decrypt_in_place( &mut self, - nonce: &GenericArray, + nonce: &Nonce, associated_data: &[u8], buffer: &mut impl Buffer, ) -> Result<(), Error> { @@ -305,10 +319,10 @@ pub trait AeadMut { /// is modified/unauthentic) fn decrypt_in_place_detached( &mut self, - nonce: &GenericArray, + nonce: &Nonce, associated_data: &[u8], buffer: &mut [u8], - tag: &GenericArray, + tag: &Tag, ) -> Result<(), Error>; } @@ -324,7 +338,7 @@ impl AeadMut for Algo { #[cfg(feature = "alloc")] fn encrypt<'msg, 'aad>( &mut self, - nonce: &GenericArray, + nonce: &Nonce, plaintext: impl Into>, ) -> Result, Error> { ::encrypt(self, nonce, plaintext) @@ -333,7 +347,7 @@ impl AeadMut for Algo { /// Encrypt the given buffer containing a plaintext message in-place. fn encrypt_in_place( &mut self, - nonce: &GenericArray, + nonce: &Nonce, associated_data: &[u8], buffer: &mut impl Buffer, ) -> Result<(), Error> { @@ -343,10 +357,10 @@ impl AeadMut for Algo { /// Encrypt the data in-place, returning the authentication tag fn encrypt_in_place_detached( &mut self, - nonce: &GenericArray, + nonce: &Nonce, associated_data: &[u8], buffer: &mut [u8], - ) -> Result, Error> { + ) -> Result, Error> { ::encrypt_in_place_detached(self, nonce, associated_data, buffer) } @@ -355,7 +369,7 @@ impl AeadMut for Algo { #[cfg(feature = "alloc")] fn decrypt<'msg, 'aad>( &mut self, - nonce: &GenericArray, + nonce: &Nonce, ciphertext: impl Into>, ) -> Result, Error> { ::decrypt(self, nonce, ciphertext) @@ -365,7 +379,7 @@ impl AeadMut for Algo { /// provided authentication tag does not match the given ciphertext. fn decrypt_in_place( &mut self, - nonce: &GenericArray, + nonce: &Nonce, associated_data: &[u8], buffer: &mut impl Buffer, ) -> Result<(), Error> { @@ -377,10 +391,10 @@ impl AeadMut for Algo { /// is modified/unauthentic) fn decrypt_in_place_detached( &mut self, - nonce: &GenericArray, + nonce: &Nonce, associated_data: &[u8], buffer: &mut [u8], - tag: &GenericArray, + tag: &Tag, ) -> Result<(), Error> { ::decrypt_in_place_detached(self, nonce, associated_data, buffer, tag) }