aead: rework traits API

.github/workflows/aead.yml

@@ -43,9 +43,6 @@ jobs:
       - run: cargo check --all-features
       - run: cargo build --target ${{ matrix.target }} --release --no-default-features
       - run: cargo build --target ${{ matrix.target }} --release --no-default-features --features alloc
-      - run: cargo build --target ${{ matrix.target }} --release --no-default-features --features bytes
-      # TODO: re-enable in v0.6.1
-      # - run: cargo build --target ${{ matrix.target }} --release --no-default-features --features heapless
       - run: cargo build --target ${{ matrix.target }} --release --no-default-features --features rand_core
 
   minimal-versions:

aead/Cargo.toml

@@ -10,25 +10,19 @@ repository = "https://github.com/RustCrypto/traits"
 license = "MIT OR Apache-2.0"
 keywords = ["crypto", "encryption"]
 categories = ["cryptography", "no-std"]
-description = """
-Traits for Authenticated Encryption with Associated Data (AEAD) algorithms,
-such as AES-GCM as ChaCha20Poly1305, which provide a high-level API
-"""
+description = "Traits for Authenticated Encryption with Associated Data (AEAD) algorithms"
 
 [dependencies]
 common = { version = "0.2", package = "crypto-common" }
 inout = "0.2.2"
 
 # optional dependencies
-arrayvec = { version = "0.7", optional = true, default-features = false }
 blobby = { version = "0.4", optional = true }
-bytes = { version = "1.11.1", optional = true, default-features = false }
 
 [features]
-default = ["rand_core"]
 alloc = []
 dev = ["blobby", "alloc"]
-getrandom = ["common/getrandom"]
+getrandom = ["common/getrandom", "rand_core"]
 rand_core = ["common/rand_core"]
 
 [lints]

aead/src/aead.rs

@@ -0,0 +1,93 @@
+use crate::{AeadCore, Error, Result};
+use alloc::vec::Vec;
+
+/// High-level functionality of Authenticated Encryption with Associated Data (AEAD) algorithms.
+pub trait Aead {
+    /// Encrypt the given plaintext payload, and return the resulting
+    /// ciphertext as a vector of bytes.
+    ///
+    /// # Errors
+    /// AEAD algorithm implementations may return an error if the plaintext or AAD are too long.
+    fn encrypt_into_vec(&self, nonce: &[u8], aad: &[u8], plaintext: &[u8]) -> Result<Vec<u8>>;
+
+    /// Decrypt the given ciphertext slice, and return the resulting plaintext
+    /// as a vector of bytes.
+    ///
+    /// # Errors
+    /// - if the `ciphertext` is inauthentic (i.e. tag verification failure)
+    /// - if the `ciphertext` is too long
+    /// - if the `aad` is too long
+    fn decrypt_into_vec(&self, nonce: &[u8], aad: &[u8], ciphertext: &[u8]) -> Result<Vec<u8>>;
+
+    /// Encrypt plaintext in `buf` extending it as necessary.
+    ///
+    /// On success, `buf` will contain the resulting ciphertext,
+    /// while on error it will be left intact.
+    ///
+    /// # Errors
+    /// AEAD algorithm implementations may return an error if the plaintext or AAD are too long.
+    #[inline]
+    fn encrypt_within_vec(&self, nonce: &[u8], aad: &[u8], buf: &mut Vec<u8>) -> Result<()> {
+        let res = self.encrypt_into_vec(nonce, aad, buf)?;
+        *buf = res;
+        Ok(())
+    }
+
+    /// Decrypt ciphertext in `buf` truncating it as necessary.
+    ///
+    /// On success, `buf` will contain the resulting plaintext,
+    /// while on error it will be zeroized.
+    ///
+    /// # Errors
+    /// - if the `ciphertext` is inauthentic (i.e. tag verification failure)
+    /// - if the `ciphertext` is too long
+    /// - if the `aad` is too long
+    #[inline]
+    fn decrypt_within_vec(&self, nonce: &[u8], aad: &[u8], buf: &mut Vec<u8>) -> Result<()> {
+        let res = self.decrypt_into_vec(nonce, aad, buf);
+        match res {
+            Ok(pt) => {
+                *buf = pt;
+                Ok(())
+            }
+            Err(err) => {
+                buf.fill(0);
+                Err(err)
+            }
+        }
+    }
+}
+
+impl<T: AeadCore> Aead for T {
+    #[inline]
+    fn encrypt_into_vec(&self, nonce: &[u8], aad: &[u8], plaintext: &[u8]) -> Result<Vec<u8>> {
+        let nonce = nonce.try_into().map_err(|_| Error)?;
+        self.encrypt_into(nonce, aad, plaintext, alloc_vec)
+    }
+
+    #[inline]
+    fn decrypt_into_vec(&self, nonce: &[u8], aad: &[u8], ciphertext: &[u8]) -> Result<Vec<u8>> {
+        let nonce = nonce.try_into().map_err(|_| Error)?;
+        self.decrypt_into(nonce, aad, ciphertext, alloc_vec)
+    }
+
+    #[inline]
+    fn encrypt_within_vec(&self, nonce: &[u8], aad: &[u8], buf: &mut Vec<u8>) -> Result<()> {
+        let nonce = nonce.try_into().map_err(|_| Error)?;
+        self.encrypt_within(nonce, aad, buf, extend_vec)
+    }
+
+    #[inline]
+    fn decrypt_within_vec(&self, nonce: &[u8], aad: &[u8], buf: &mut Vec<u8>) -> Result<()> {
+        let nonce = nonce.try_into().map_err(|_| Error)?;
+        self.decrypt_within(nonce, aad, buf, Vec::truncate)
+    }
+}
+
+fn alloc_vec(len: usize) -> Vec<u8> {
+    alloc::vec![0u8; len]
+}
+
+fn extend_vec(buf: &mut Vec<u8>, len: usize) {
+    buf.resize(len, 0);
+}

aead/src/dev.rs

@@ -1,13 +1,8 @@
 //! Development-related functionality
 
-#![allow(clippy::missing_errors_doc, reason = "dev module")]
-#![allow(clippy::missing_panics_doc, reason = "dev module")]
-#![allow(clippy::unwrap_in_result, reason = "dev module")]
-
-use crate::{
-    Aead, AeadInOut, Payload, Tag, TagPosition, array::typenum::Unsigned, inout::InOutBuf,
-};
 pub use blobby;
+
+use crate::Aead;
 use common::KeyInit;
 
 /// AEAD test vector
@@ -26,8 +21,11 @@ pub struct TestVector {
 }
 
 /// Run AEAD test for the provided passing test vector
-#[allow(clippy::cast_possible_truncation)]
-pub fn pass_test<C: AeadInOut + KeyInit>(
+///
+/// # Errors
+/// - If the cipher has failed initialization with the provided key.
+/// - If the AEAD mode has failed to pass the test vector.
+pub fn pass_test<C: Aead + KeyInit>(
     &TestVector {
         key,
         nonce,
@@ -36,76 +34,45 @@ pub fn pass_test<C: AeadInOut + KeyInit>(
         ciphertext,
     }: &TestVector,
 ) -> Result<(), &'static str> {
-    let nonce = nonce.try_into().expect("wrong nonce size");
-    let cipher = <C as KeyInit>::new_from_slice(key).expect("failed to initialize the cipher");
+    let cipher: C = KeyInit::new_from_slice(key).map_err(|_| "failed to initialize the cipher")?;
 
     let res = cipher
-        .encrypt(
-            nonce,
-            Payload {
-                aad,
-                msg: plaintext,
-            },
-        )
+        .encrypt_into_vec(nonce, aad, plaintext)
         .map_err(|_| "encryption failure")?;
     if res != ciphertext {
         return Err("encrypted data is different from target ciphertext");
     }
 
     let res = cipher
-        .decrypt(
-            nonce,
-            Payload {
-                aad,
-                msg: ciphertext,
-            },
-        )
+        .decrypt_into_vec(nonce, aad, ciphertext)
         .map_err(|_| "decryption failure")?;
     if res != plaintext {
         return Err("decrypted data is different from target plaintext");
     }
 
-    let (ct, tag) = match C::TAG_POSITION {
-        TagPosition::Prefix => {
-            let (tag, ct) = ciphertext.split_at(C::TagSize::USIZE);
-            (ct, tag)
-        }
-        TagPosition::Postfix => ciphertext.split_at(plaintext.len()),
-    };
-    let tag: &Tag<C> = tag.try_into().expect("tag has correct length");
+    let mut buf = ciphertext.to_vec();
 
-    // Fill output buffer with "garbage" to test that its data does not get read during encryption
-    let mut buf: alloc::vec::Vec<u8> = (0..plaintext.len()).map(|i| i as u8).collect();
-    let inout_buf = InOutBuf::new(plaintext, &mut buf).expect("pt and buf have the same length");
+    // Flip one bit
+    buf[0] ^= 1;
 
-    let calc_tag = cipher
-        .encrypt_inout_detached(nonce, aad, inout_buf)
-        .map_err(|_| "encrypt_inout_detached: encryption failure")?;
-    if tag != &calc_tag {
-        return Err("encrypt_inout_detached: tag mismatch");
-    }
-    if ct != buf {
-        return Err("encrypt_inout_detached: ciphertext mismatch");
-    }
+    let res = cipher.decrypt_within_vec(nonce, aad, &mut buf);
 
-    // Fill output buffer with "garbage"
-    buf.iter_mut()
-        .enumerate()
-        .for_each(|(i, v): (usize, &mut u8)| *v = i as u8);
-
-    let inout_buf = InOutBuf::new(ct, &mut buf).expect("ct and buf have the same length");
-    cipher
-        .decrypt_inout_detached(nonce, aad, inout_buf, tag)
-        .map_err(|_| "decrypt_inout_detached: decryption failure")?;
-    if plaintext != buf {
-        return Err("decrypt_inout_detached: plaintext mismatch");
+    if res.is_ok() {
+        return Err("did not detect corrupted ciphertext");
+    }
+    if buf.iter().any(|&b| b != 0) {
+        return Err("the buffer was not zeroized after failure");
     }
 
     Ok(())
 }
 
 /// Run AEAD test for the provided failing test vector
-pub fn fail_test<C: AeadInOut + KeyInit>(
+///
+/// # Errors
+/// - If the cipher has failed initialization with the provided key.
+/// - If the cipher has passed the test vector.
+pub fn fail_test<C: Aead + KeyInit>(
     &TestVector {
         key,
         nonce,
@@ -114,26 +81,32 @@ pub fn fail_test<C: AeadInOut + KeyInit>(
         ..
     }: &TestVector,
 ) -> Result<(), &'static str> {
-    let nonce = nonce.try_into().expect("wrong nonce size");
-    let cipher = <C as KeyInit>::new_from_slice(key).expect("failed to initialize the cipher");
+    let cipher: C = KeyInit::new_from_slice(key).map_err(|_| "failed to initialize the cipher")?;
 
-    let res = cipher.decrypt(
-        nonce,
-        Payload {
-            aad,
-            msg: ciphertext,
-        },
-    );
+    let res = cipher.decrypt_into_vec(nonce, aad, ciphertext);
     if res.is_ok() {
-        Err("decryption must return error")
-    } else {
-        Ok(())
+        return Err("decryption must return error");
     }
+
+    let mut buf = ciphertext.to_vec();
+    let res = cipher.decrypt_within_vec(nonce, aad, &mut buf);
+
+    if res.is_ok() {
+        return Err("decryption must return error");
+    }
+    if buf.iter().any(|&b| b != 0) {
+        return Err("the buffer was not zeroized after failure");
+    }
+
+    Ok(())
 }
 
 /// Define AEAD test for passing test vectors
 #[macro_export]
 macro_rules! new_pass_test {
+    ($name:ident, $cipher:ty $(,)?) => {
+        $crate::new_pass_test!($name, stringify!($name), $cipher);
+    };
     ($name:ident, $test_name:expr, $cipher:ty $(,)?) => {
         #[test]
         fn $name() {
@@ -165,6 +138,9 @@ macro_rules! new_pass_test {
 /// Define AEAD test for failing test vectors
 #[macro_export]
 macro_rules! new_fail_test {
+    ($name:ident, $cipher:ty $(,)?) => {
+        $crate::new_fail_test!($name, stringify!($name), $cipher);
+    };
     ($name:ident, $test_name:expr, $cipher:ty $(,)?) => {
         #[test]
         fn $name() {