Adapt test framework, tests and CLI to the trait split, update release notes

Author: Quant-TheodoreFelix

alpha_0.1.2_release_notes.md

@@ -17,8 +17,9 @@
 * Ensure that all crates have `#![forbid(missing_docs)]`
 * Apply Secret trait consistently across the library --> study the `Zeroize` trait in RustCrypto
 * Change all "[u8;0]" to "[]" throughout the code and docs ... or better yet, change the APIs to take an Option<>
-* Change all `-> Vec<u8>` to `-> [u8; CONST_LEN]`, and the `output: &mut [u8]` to `output: &mut [u8; CONST_LEN]` where
-  appropriate.
+* Change the `output: &mut [u8]` to `output: &mut [u8; CONST_LEN]` where appropriate. (The `-> Vec<u8>` half of this
+  item is done, see changelog. The `*_out` slice parameters were deliberately left as `&mut [u8]` because the
+  documented truncation / oversized-buffer semantics depend on them; revisit per-API.)
 * Probably it makes sense to leave Hex and Base64 as requiring std; ... or maybe add a no_std version that uses
   fixed-sized blocks?
 * Create a cargo feature #[cfg(feature='rng')] and put it around things like keygen that takes an rng so that the build
@@ -52,6 +53,15 @@
 
 * ML-DSA
 * Low-Memory ML-DSA -- runs in about 1/10th of the usual memory (~ 30 kb of stack) with only minor performance impact.
+* (Breaking, progress on #14) Removed all heap-allocating `-> Vec<u8>` functions from the `Hash` and `MAC` traits
+  (`hash`, `do_final`, `do_final_partial_bits`, `mac`). They are replaced by the new `HashFixedOutput<const OUTPUT_LEN>`
+  and `MACFixedOutput<const OUTPUT_LEN>` traits which return `[u8; OUTPUT_LEN]` stack arrays, following the same
+  const-generic pattern as the `KEM` and `Signature` traits. All concrete algorithms (SHA2, SHA3, HMAC) implement the
+  new traits; the factory enums keep only the `*_out` functions because their output length is a runtime property.
+  The XOF functions (`hash_xof`, `squeeze`) keep returning `Vec<u8>` because their output length is inherently a
+  runtime parameter.
+* HMAC no longer heap-allocates its intermediate inner digest (was an internal `vec!`, now a fixed stack buffer),
+  and the inner digest buffer is zeroized after use.
 * All public `*_out(.., out: &mut [u8])` functions now begin by zeroizing the entire output buffer with `.fill(0)`,
   preventing exposure of stale data in oversized output buffers or on early error returns.
 * Github issues resolved:

cli/src/mac_cmd.rs

@@ -63,14 +63,17 @@ fn do_mac(mut mac: impl MAC, verify_val: &Option<String>, output_hex: bool) {
 
     if verify_val.is_none() {
         // compute a MAC value
-        let out = mac.do_final();
+        let mut out = [0u8; 64];
+        let bytes_written =
+            mac.do_final_out(&mut out).expect("Failed to compute the MAC value");
+        let out = &out[..bytes_written];
 
         if output_hex {
             for b in out.iter() {
                 print!("{b:02x}");
             }
         } else {
-            io::stdout().write(&out).unwrap();
+            io::stdout().write(out).unwrap();
         }
         println!();
     } else {

cli/src/sha2_cmd.rs

@@ -24,12 +24,14 @@ fn do_sha2(mut sha2: impl Hash, output_hex: bool) {
         bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
     }
 
-    let out = sha2.do_final();
+    let mut out = [0u8; 64];
+    let bytes_written = sha2.do_final_out(&mut out);
+    let out = &out[..bytes_written];
 
     if output_hex {
         for b in out.iter() {
             print!("{b:02x}");
         }
-    } else { io::stdout().write(&out).unwrap(); }
+    } else { io::stdout().write(out).unwrap(); }
     println!();
 }

cli/src/sha3_cmd.rs

@@ -25,13 +25,15 @@ fn do_sha3(mut sha3: impl Hash, output_hex: bool) {
         bytes_read = io::stdin().read(&mut buf).expect("Failed to read from stdin");
     }
 
-    let out = sha3.do_final();
+    let mut out = [0u8; 64];
+    let bytes_written = sha3.do_final_out(&mut out);
+    let out = &out[..bytes_written];
 
     if output_hex {
         for b in out.iter() {
             print!("{b:02x}");
         }
-    } else { io::stdout().write(&out).unwrap(); }
+    } else { io::stdout().write(out).unwrap(); }
     println!();
 }
 

crypto/core-test-framework/src/hash.rs

@@ -1,4 +1,4 @@
-use bouncycastle_core::traits::{Hash, HashAlgParams};
+use bouncycastle_core::traits::{HashAlgParams, HashFixedOutput};
 
 pub struct TestFrameworkHash {
     pub enable_partial_final_input_tests: bool,
@@ -13,30 +13,31 @@ impl TestFrameworkHash {
     /// This gives good baseline test coverage, but is not exhaustive; for example it does not test
     /// do_final_partial_bits() or do_final_partial_bits_out()
     /// because those require different input-output pairs.
-    pub fn test_hash<H: Hash + HashAlgParams + Default>(
+    pub fn test_hash<H: HashFixedOutput<N> + HashAlgParams + Default, const N: usize>(
         &self,
         input: &[u8],
         expected_output: &[u8],
     ) {
         /*** fn result_len() -> usize ***/
         assert_eq!(H::default().output_len(), H::OUTPUT_LEN);
+        assert_eq!(N, H::OUTPUT_LEN);
 
-        /*** fn hash(self, data: &[u8]) -> Vec<u8> **/
-        let output_vec = H::default().hash(input);
-        assert_eq!(output_vec, expected_output);
+        /*** fn hash(self, data: &[u8]) -> [u8; N] **/
+        let output_arr = H::default().hash(input);
+        assert_eq!(&output_arr[..], expected_output);
 
         /*** fn hash_out(self, data: &[u8], output: &mut [u8]) -> Result<usize, HashError> ***/
         let mut output_buf = vec![0_u8; H::OUTPUT_LEN];
         H::default().hash_out(input, &mut output_buf);
         assert_eq!(output_buf, expected_output);
 
         /*** fn do_update(&mut self, data: &[u8]) -> Result<(), HashError> ***/
-        /*** fn do_final(self) -> Result<Vec<u8>, HashError> **/
+        /*** fn do_final(self) -> [u8; N] **/
 
         let mut message_digest = H::default();
         message_digest.do_update(input);
         let output_buf = message_digest.do_final();
-        assert_eq!(expected_output, output_buf, "Incorrect output for input (update_bytes)");
+        assert_eq!(expected_output, &output_buf[..], "Incorrect output for input (update_bytes)");
 
         for length in 1..output_buf.len() {
             let mut truncated = vec![0_u8; length];
@@ -58,7 +59,7 @@ impl TestFrameworkHash {
             message_digest.do_update(chunk);
         }
         let output_buf = message_digest.do_final();
-        assert_eq!(expected_output, output_buf, "Incorrect output for input (update_bytes)");
+        assert_eq!(expected_output, &output_buf[..], "Incorrect output for input (update_bytes)");
 
         /*** fn do_update(&mut self, data: &[u8]) -> Result<(), HashError> ***/
         /*** fn do_final_out(self, output: &mut [u8]) -> Result<usize, HashError> ***/

crypto/core-test-framework/src/mac.rs

@@ -1,7 +1,7 @@
 use crate::DUMMY_SEED_512;
 use bouncycastle_core::errors::{KeyMaterialError, MACError};
 use bouncycastle_core::key_material::{KeyMaterial512, KeyType, KeyMaterialTrait};
-use bouncycastle_core::traits::MAC;
+use bouncycastle_core::traits::MACFixedOutput;
 use bouncycastle_core::traits::{SecurityStrength};
 
 pub struct TestFrameworkMAC {
@@ -15,15 +15,15 @@ impl TestFrameworkMAC {
 
     /// Test all the members of trait Hash against the given input-output pair.
     /// This gives good baseline test coverage, but is not exhaustive.
-    pub fn test_mac<M: MAC>(
+    pub fn test_mac<M: MACFixedOutput<N>, const N: usize>(
         &self,
         key: &impl KeyMaterialTrait,
         input: &[u8],
         expected_output: &[u8],
     ) {
         // Test ::mac()
         let out = M::new_allow_weak_key(key).unwrap().mac(input);
-        assert_eq!(out, expected_output);
+        assert_eq!(&out[..], expected_output);
 
         // Test ::mac_out
         let mut out = vec![0u8; expected_output.len()];
@@ -53,7 +53,7 @@ impl TestFrameworkMAC {
         let output_len = mac.output_len();
         mac.do_update(input);
         let out = mac.do_final();
-        assert_eq!(out, expected_output);
+        assert_eq!(&out[..], expected_output);
 
         // Test .output_len()
         assert_eq!(output_len, out.len());

crypto/core-test-framework/src/signature.rs

@@ -254,14 +254,16 @@ impl TestFrameworkSignature {
 
         // sign_ph
         let (pk, sk) = SigAlg::keygen().unwrap();
-        let ph: [u8; PH_LEN] = HASH::default().hash(msg)[..PH_LEN].try_into().unwrap();
+        let mut ph = [0u8; PH_LEN];
+        HASH::default().hash_out(msg, &mut ph);
         let sig_val = SigAlg::sign_ph(&sk, &ph, None).unwrap();
         SigAlg::verify(&pk, msg, None, &sig_val).unwrap();
         SigAlg::verify_ph(&pk, &ph, None, &sig_val).unwrap();
 
         // sign_ph_out
         let (pk, sk) = SigAlg::keygen().unwrap();
-        let ph: [u8; PH_LEN] = HASH::default().hash(msg)[..PH_LEN].try_into().unwrap();
+        let mut ph = [0u8; PH_LEN];
+        HASH::default().hash_out(msg, &mut ph);
         let mut sig_val = [0u8; SIG_LEN];
         let bytes_written = SigAlg::sign_ph_out(&sk, &ph, None, &mut sig_val).unwrap();
         assert_eq!(bytes_written, SIG_LEN);