diff --git a/aead/src/lib.rs b/aead/src/lib.rs index 700667998..d13a7e485 100644 --- a/aead/src/lib.rs +++ b/aead/src/lib.rs @@ -380,6 +380,63 @@ pub trait AeadMutInPlace: AeadCore { ) -> Result<()>; } +/// In-place stateless AEADs that support additional processing on the expected +/// tag before comparing the result to the received tag. +/// +/// # ⚠️Hazmat Trait +/// +/// This trait was added to allow implementation of committing AEAD wrappers +/// like CTX which require access to the expected tag at decryption time. +/// **Incorrect usage of this trait can destroy the integrity guarantees that +/// an AEAD otherwise provides. Unless you know exactly what you're doing and +/// have a good reason to need the expected tag's value beyond checking the +/// received tag's correctness, do not use this trait's function.** +pub trait DelegatedAuthenticityAeadInPlace: AeadInPlace { + /// Decrypt the data in-place, returning an error in the event the provided + /// authentication tag does not match the given ciphertext (i.e. ciphertext + /// is modified/unauthentic), with additional tag processing + /// + /// The `tag_closure` argument is a function that receives the expected tag + /// and performs a computation on it to produce a new value that can then be + /// directly compared to the received tag. + fn decrypt_in_place_detached_with_tag_processing>( + &self, + nonce: &Nonce, + associated_data: &[u8], + buffer: &mut [u8], + received_tag: GenericArray, + tag_closure: impl Fn(&Tag) -> GenericArray, + ) -> Result<()>; +} +/// In-place stateful AEADs that support additional processing on the expected +/// tag before comparing the result to the received tag. +/// +/// # ⚠️Hazmat Trait +/// +/// This trait was added to allow implementation of committing AEAD wrappers +/// like CTX which require access to the expected tag at decryption time. +/// **Incorrect usage of this trait can destroy the integrity guarantees that +/// an AEAD otherwise provides. Unless you know exactly what you're doing and +/// have a good reason to need the expected tag's value beyond checking the +/// received tag's correctness, do not use this trait's function.** +pub trait DelegatedAuthenticityAeadMutInPlace: AeadMutInPlace { + /// Decrypt the data in-place, returning an error in the event the provided + /// authentication tag does not match the given ciphertext (i.e. ciphertext + /// is modified/unauthentic), with additional tag processing + /// + /// The `tag_closure` argument is a function that receives the expected tag + /// and performs a computation on it to produce a new value that can then be + /// directly compared to the received tag. + fn decrypt_in_place_detached_with_tag_processing>( + &mut self, + nonce: &Nonce, + associated_data: &[u8], + buffer: &mut [u8], + received_tag: GenericArray, + tag_closure: impl Fn(&Tag) -> GenericArray, + ) -> Result<()>; +} + #[cfg(feature = "alloc")] impl Aead for Alg { fn encrypt<'msg, 'aad>(