kmac: Refactor Rate trait based implementation

Integrating comments from @newpavlov's code review.

- Remove the messy impl kmac macro in favour of a cleaner trait system
  approach.
- Clean up test vectors and use hex-literal, and use raw NIST vectors
  copy/pasted from the PDFs to make review easier.
- Move public API tests into tests/kmac.rs
- Remove std from the std tests.
- Remove the bench_full benchmarks, we will discuss this in a separate PR.
- Adjust docstrings and README for completeness.

Author: hoxxep

.github/workflows/kmac.yml

@@ -29,7 +29,7 @@ jobs:
           - thumbv7em-none-eabi
           - wasm32-unknown-unknown
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: RustCrypto/actions/cargo-cache@master
       - uses: dtolnay/rust-toolchain@master
         with:
@@ -38,8 +38,6 @@ jobs:
       - run: cargo build --no-default-features --target ${{ matrix.target }}
 
   minimal-versions:
-    # disabled until belt-block gets published
-    if: false
     uses: RustCrypto/actions/.github/workflows/minimal-versions.yml@master
     with:
       working-directory: ${{ github.workflow }}
@@ -52,7 +50,7 @@ jobs:
           - 1.85.0 # MSRV
           - stable
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: RustCrypto/actions/cargo-cache@master
       - uses: dtolnay/rust-toolchain@master
         with:

kmac/README.md

@@ -16,7 +16,7 @@ The below table summarises the equivalence with other MAC algorithms, where `K`
 
 | Existing MAC Algorithm | KMAC Equivalent              |
 |------------------------|------------------------------|
-| `AES-KMAC(K, text)`    | `KMAC128(K, text, L=128, S)` |
+| `AES-CMAC(K, text)`    | `KMAC128(K, text, L=128, S)` |
 | `HMAC-SHA256(K, text)` | `KMAC256(K, text, L=256, S)` |
 | `HMAC-SHA512(K, text)` | `KMAC256(K, text, L=512, S)` |
 
@@ -63,13 +63,13 @@ let mac_bytes = hex!("
 kmac.verify_slice(&mac_bytes).unwrap();
 ```
 
-### Producing a fixed-length output
+### Producing a custom-length output
 
-KMAC can also be used to produce an output of any length, which is particularly useful when KMAC is being used as a [key-derivation function (KDF)](https://en.wikipedia.org/wiki/Key_derivation_function).
+KMAC can produce an output of any length via `finalize_into_buf`, which is particularly useful when KMAC is being used as a [key-derivation function (KDF)](https://en.wikipedia.org/wiki/Key_derivation_function).
 
-This method finalizes the KMAC and mixes the requested output length into the KMAC domain separation. The resulting bytes are dependent on the exact length of `out`. Use this when the output length is part of the MAC/derivation semantics (for example when the length itself must influence the MAC result).
+This method mixes the requested output length into the KMAC domain separation, so the resulting bytes depend on the exact length of `out`. This is distinct from both `finalize()` (which uses the type's default output length) and `finalize_xof()` (KMACXOF, which does not bind output length at all).
 
-A customisation string can also be provided to further domain-separate different uses of KMAC with the same key when initialising the KMAC instance with `new_customization`.
+A customisation string can also be provided via `new_customization` to further domain-separate different uses of KMAC with the same key.
 
 ```rust
 use kmac::{Kmac256, Mac};
@@ -87,11 +87,9 @@ let expected = hex!("
 assert_eq!(output[..], expected[..]);
 ```
 
-### Producing a variable-length output
+### KMACXOF: variable-length output
 
-Variable length KMAC output uses the `ExtendableOutput` trait. This is useful when the desired output length is not immediately known, and will append data to a buffer until the desired length is reached. 
-
-The XOF variant finalizes the sponge state without binding the requested output length into the KMAC domain separation. The returned reader yields an effectively infinite stream of bytes; reading the first `N` bytes  from the reader (and truncating) produces the same `N`-byte prefix regardless of whether more bytes will be read later.
+KMACXOF (defined in Section 4.3.1 of [NIST SP 800-185]) produces an arbitrary-length output via the `ExtendableOutput` trait. Unlike `finalize()` and `finalize_into_buf()`, KMACXOF does not bind the output length into the domain separation — the returned reader yields an effectively infinite stream of bytes, and reading the first `N` bytes produces the same `N`-byte prefix regardless of how many bytes are read in total.
 
 ```rust
 use kmac::{Kmac256, Mac, ExtendableOutput, XofReader};

kmac/benches/mod.rs

@@ -2,48 +2,9 @@
 extern crate test;
 
 use core::hint::black_box;
-use kmac::{KeyInit, Kmac128, Kmac256, Mac};
+use kmac::{KeyInit, Kmac128, Kmac256};
 use test::Bencher;
 
-#[macro_export]
-macro_rules! bench_full {
-    (
-        $init:expr;
-        $($name:ident $bs:expr;)*
-    ) => {
-        $(
-            #[bench]
-            fn $name(b: &mut Bencher) {
-                let data = [0; $bs];
-
-                b.iter(|| {
-                    let mut d = $init;
-                    digest::Update::update(&mut d, black_box(&data[..]));
-                    black_box(d.finalize());
-                });
-
-                b.bytes = $bs;
-            }
-        )*
-    };
-}
-
-bench_full!(
-    Kmac128::new(black_box(&Default::default()));
-    kmac128_10 10;
-    kmac128_100 100;
-    kmac128_1000 1000;
-    kmac128_10000 10000;
-);
-
-bench_full!(
-    Kmac256::new(black_box(&Default::default()));
-    kmac256_10 10;
-    kmac256_100 100;
-    kmac256_1000 1000;
-    kmac256_10000 10000;
-);
-
 digest::bench_update!(
     Kmac128::new(black_box(&Default::default()));
     kmac128_update_10 10;

kmac/src/encoding.rs

@@ -25,11 +25,9 @@ pub(crate) fn right_encode(num: u64, buffer: &mut [u8; 9]) -> &[u8] {
 #[cfg(test)]
 mod tests {
     use super::*;
-    extern crate std;
 
     #[test]
     fn test_num_encoding_size() {
-        // sha3::block_api::Sha3ReaderCore::<sha3::Sha3_256>::new(&[0; 200]);
         let test_cases = [
             (0, 1),
             (1, 1),
@@ -75,10 +73,17 @@ mod tests {
 
         for i in 0..usize::BITS {
             let x: usize = 1 << i;
-            let mut want = std::vec![0; 1];
-            want.extend(x.to_be_bytes().iter().skip_while(|&&v| v == 0));
-            want[0] = (want.len() - 1) as u8;
-            assert_eq!(left_encode(x as u64, &mut buf), want, "#{x}");
+            let be_bytes = x.to_be_bytes();
+            let skip = be_bytes
+                .iter()
+                .position(|&v| v != 0)
+                .unwrap_or(be_bytes.len() - 1);
+            let len = be_bytes.len() - skip;
+            let mut want = [0u8; 9];
+            want[0] = len as u8;
+            want[1..=len].copy_from_slice(&be_bytes[skip..]);
+            let total_len = len + 1;
+            assert_eq!(left_encode(x as u64, &mut buf), &want[..total_len], "#{x}");
         }
     }
 
@@ -93,10 +98,17 @@ mod tests {
 
         for i in 0..usize::BITS {
             let x: usize = 1 << i;
-            let mut want =
-                std::vec::Vec::from_iter(x.to_be_bytes().iter().copied().skip_while(|&v| v == 0));
-            want.push(want.len() as u8);
-            assert_eq!(right_encode(x as u64, &mut buf), want, "#{x}");
+            let be_bytes = x.to_be_bytes();
+            let skip = be_bytes
+                .iter()
+                .position(|&v| v != 0)
+                .unwrap_or(be_bytes.len() - 1);
+            let len = be_bytes.len() - skip;
+            let mut want = [0u8; 9];
+            want[..len].copy_from_slice(&be_bytes[skip..]);
+            want[len] = len as u8;
+            let total_len = len + 1;
+            assert_eq!(right_encode(x as u64, &mut buf), &want[..total_len], "#{x}");
         }
     }
 }