XOF extends Hash: SHAKE128 and SHAKE256 are hashes, and squeezing gets its own type

CLAUDE.md

@@ -54,9 +54,15 @@ Quality / mutation testing:
 
 ```
 ./dev_scripts/quality_stats.sh ./crypto    # lines-of-code, docstring & fallibility metrics; CI publishes this
-cargo mutants                              # config in .cargo/mutants.toml (output: custom_mutants_output/)
+cargo mutants -p bouncycastle-sha3         # config in .cargo/mutants.toml (output: custom_mutants_output/)
 ```
 
+`-p` is as non-optional here as `--workspace` is for build and test, and for the same reason: a bare
+`cargo mutants` examines only the root `bouncycastle` package, whose single `src/lib.rs` yields no
+mutants, so it prints "No mutants found under the active filters" and exits **0**. See
+[the mutation-testing mechanics](#notes-on-testing) for scoping a run to one file, for crates whose
+tests live elsewhere, and for the test-data symlink.
+
 Stack-memory benches are separate binaries under `mem_usage_benches/src/`, each declared as a
 `[[bin]]` in that crate's `Cargo.toml`:
 
@@ -165,7 +171,11 @@ Rules when working from the downloaded copy:
 What a crate must be tested against — including the mutation-testing expectation, the trait test framework, and the
 external vector suites — is specified in QUALITY_AND_STYLE.md and CONTRIBUTING.md. Repo-specific mechanics:
 
-- `cargo mutants` is expected to be run on each crate; surviving mutants must be investigated but not all need to die (e.g. XOR/OR equivalences in crypto code are acceptable). Config lives in `.cargo/mutants.toml` (output dir `custom_mutants_output/`).
+- `cargo mutants` is expected to be run on each crate; surviving mutants must be investigated but not all need to die (e.g. XOR/OR equivalences in crypto code are acceptable). Config lives in `.cargo/mutants.toml` (output dir `custom_mutants_output/`). Four things about running it here:
+  - **Always pass `-p <crate>`.** Without it only the root package is examined, which has no mutants, and the run "passes" vacuously — see [Common commands](#common-commands).
+  - **`-f`/`--file` does nothing while the checked-in config is in play**, because its `examine_globs` wins over the CLI filter: `cargo mutants -p bouncycastle-sha3 -f '**/kmac.rs'` still examines all ~874 mutants in the crate. To scope a run to the files you changed, copy `.cargo/mutants.toml` somewhere outside the repo, delete its `examine_globs` block, and pass `--config <copy>`; `-f` then filters as documented. (`--config /dev/null` also works but throws away `skip_calls`, `error_values`, `cap_lints` and the timeout multipliers with it.)
+  - **Add `--test-workspace true` when a crate's mutants are killed by another crate's tests.** The `core` traits are the case that matters: their default method bodies are exercised from `sha3` and `factory`, so a `-p bouncycastle-core` run alone reports them all as missed.
+  - **Symlink the test data into `/tmp`.** `cargo mutants` copies the tree to `/tmp/cargo-mutants-<dir>-XXXX.tmp/`, so the `../../../bc-test-data/...` paths the vector suites use resolve to `/tmp/bc-test-data`. Without `ln -s <path-to>/bc-test-data /tmp/bc-test-data` those tests print their "not found" warning, pass vacuously, and every mutant they would have killed is reported as missed. Use `--jobs 3` and an explicit `--timeout`; note that a mutant which makes a squeeze return no bytes hangs a fill loop for real, so some timeouts are kills rather than false alarms.
 - Integration tests in `tests/` are preferred over in-file `#[cfg(test)] mod tests` blocks — see "Unit tests vs integration tests" in QUALITY_AND_STYLE.md for the reasoning and the exceptions. A unit test is justified for high-risk code that has known-answer values and cannot be reached through the public API; when you write one, all of its helpers go inside that `mod tests`.
 - A property that can be asserted at compile time (`const _: () = assert!(...)`) stays a compile-time assertion even when a test also covers it: `cargo mutants` cannot see a const assertion fail, so pair the two rather than trading the guarantee for the coverage.
 - For traits in `core`, the canonical tests live in `core-test-framework` and are invoked from each implementor's integration tests — don't duplicate them per-implementation.

cli/src/mac_cmd.rs

@@ -8,6 +8,7 @@ use bouncycastle::core::key_material::{
 use bouncycastle::core::traits::MAC;
 use bouncycastle::hex;
 use bouncycastle::sha2::hmac::{HMAC_SHA256, HMAC_SHA512, HMAC_SHA512_224, HMAC_SHA512_256};
+use bouncycastle::sha3::{KMAC128, KMAC256};
 use bouncycastle::sm3::hmac::HMAC_SM3;
 
 #[allow(non_camel_case_types)]
@@ -19,14 +20,8 @@ pub(crate) enum HMACVariant {
     SM3,
 }
 
-pub(crate) fn mac_cmd(
-    hmac_variant: HMACVariant,
-    key: &Option<String>,
-    key_file: &Option<String>,
-    verify_val: &Option<String>,
-    output_hex: bool,
-) {
-    // load the key
+/// Loads a MAC key from `--key` (hex) or `--key-file` (raw), tagged as a MAC key.
+fn load_mac_key(key: &Option<String>, key_file: &Option<String>) -> KeyMaterial512 {
     let key_bytes: Vec<u8> = if key.is_some() {
         hex::decode(key.as_ref().unwrap()).unwrap()
     } else if key_file.is_some() {
@@ -42,6 +37,17 @@ pub(crate) fn mac_cmd(
     }
     let mut key = KeyMaterial512::from_bytes(&key_bytes).unwrap();
     do_hazardous_operations(&mut key, |key| key.set_key_type(KeyType::MACKey)).unwrap();
+    key
+}
+
+pub(crate) fn mac_cmd(
+    hmac_variant: HMACVariant,
+    key: &Option<String>,
+    key_file: &Option<String>,
+    verify_val: &Option<String>,
+    output_hex: bool,
+) {
+    let key = load_mac_key(key, key_file);
 
     // instantiate the MAC object and call do_mac()
     match hmac_variant {
@@ -68,6 +74,36 @@ pub(crate) fn mac_cmd(
     }
 }
 
+/// KMAC (NIST SP 800-185 Sec 4), which unlike HMAC takes a customization string and a caller-
+/// chosen tag length -- both are bound into the computation, so the verifier must use the same.
+pub(crate) fn kmac_cmd(
+    bit_len: usize,
+    length: usize,
+    customization: &Option<String>,
+    key: &Option<String>,
+    key_file: &Option<String>,
+    verify_val: &Option<String>,
+    output_hex: bool,
+) {
+    let key = load_mac_key(key, key_file);
+    let s = customization.as_deref().unwrap_or("").as_bytes();
+    // new_allow_weak_key, as the HMAC commands do: a CLI is used for test vectors and scripting,
+    // where a short or all-zero key is a legitimate thing to want.
+    match bit_len {
+        128 => do_mac(
+            KMAC128::new_with_params(&key, s, length, true).expect("a valid MAC key"),
+            verify_val,
+            output_hex,
+        ),
+        256 => do_mac(
+            KMAC256::new_with_params(&key, s, length, true).expect("a valid MAC key"),
+            verify_val,
+            output_hex,
+        ),
+        _ => panic!("Unsupported algorithm: KMAC-{bit_len}"),
+    }
+}
+
 fn do_mac(mut mac: impl MAC, verify_val: &Option<String>, output_hex: bool) {
     // read the content to be MAC'd from stdin
     let mut buf: [u8; 1024] = [0u8; 1024];

cli/src/main.rs

@@ -158,6 +158,180 @@ enum Subcommands {
         x: bool,
     },
 
+    /// Perform TupleHash128 (NIST SP 800-185 Sec 5) over a tuple of strings. The tuple is given
+    /// by repeated --element flags, each in hex; with none, stdin is hashed as a single element.
+    /// The boundaries between elements are part of the hash.
+    TUPLEHASH128 {
+        /// Length of the output in bytes.
+        length: usize,
+
+        #[arg(short = 'e', long = "element")]
+        /// A tuple element, in hex. Repeat for each element, in order.
+        elements: Vec<String>,
+
+        #[arg(short = 's', long)]
+        /// Customization string.
+        customization: Option<String>,
+
+        #[arg(short)]
+        /// Output the hashes in hex format.
+        x: bool,
+    },
+
+    /// Perform TupleHash256 (NIST SP 800-185 Sec 5). See tuplehash128.
+    TUPLEHASH256 {
+        /// Length of the output in bytes.
+        length: usize,
+
+        #[arg(short = 'e', long = "element")]
+        /// A tuple element, in hex. Repeat for each element, in order.
+        elements: Vec<String>,
+
+        #[arg(short = 's', long)]
+        /// Customization string.
+        customization: Option<String>,
+
+        #[arg(short)]
+        /// Output the hashes in hex format.
+        x: bool,
+    },
+
+    /// Perform ParallelHash128 (NIST SP 800-185 Sec 6) of the content provided on stdin.
+    /// The block size is part of the function: the same input under a different block size gives
+    /// an unrelated hash, so both sides must use the same value.
+    /// Supports streaming update for low memory footprint.
+    PARALLELHASH128 {
+        /// Length of the output in bytes.
+        length: usize,
+
+        #[arg(short = 'b', long)]
+        /// Block size B in bytes, for the parallel split.
+        block_size: usize,
+
+        #[arg(short = 's', long)]
+        /// Customization string.
+        customization: Option<String>,
+
+        #[arg(short)]
+        /// Output the hashes in hex format.
+        x: bool,
+    },
+
+    /// Perform ParallelHash256 (NIST SP 800-185 Sec 6). See parallelhash128.
+    PARALLELHASH256 {
+        /// Length of the output in bytes.
+        length: usize,
+
+        #[arg(short = 'b', long)]
+        /// Block size B in bytes, for the parallel split.
+        block_size: usize,
+
+        #[arg(short = 's', long)]
+        /// Customization string.
+        customization: Option<String>,
+
+        #[arg(short)]
+        /// Output the hashes in hex format.
+        x: bool,
+    },
+
+    /// Compute or verify a KMAC128 (NIST SP 800-185 Sec 4) over the content provided on stdin.
+    /// The tag length and customization string are bound into the computation, so the verifier
+    /// must use the same values.
+    KMAC128 {
+        /// Length of the tag in bytes.
+        length: usize,
+
+        #[arg(short = 's', long)]
+        /// Customization string, domain-separating this use of KMAC from another.
+        customization: Option<String>,
+
+        #[arg(short, long)]
+        /// The key, in hex.
+        key: Option<String>,
+
+        #[arg(long)]
+        /// File containing the key, as raw bytes.
+        key_file: Option<String>,
+
+        #[arg(short, long)]
+        /// Verify against this tag (hex) instead of computing one.
+        verify: Option<String>,
+
+        #[arg(short)]
+        /// Output the tag in hex format.
+        x: bool,
+    },
+
+    /// Compute or verify a KMAC256 (NIST SP 800-185 Sec 4) over the content provided on stdin.
+    /// See kmac128.
+    KMAC256 {
+        /// Length of the tag in bytes.
+        length: usize,
+
+        #[arg(short = 's', long)]
+        /// Customization string, domain-separating this use of KMAC from another.
+        customization: Option<String>,
+
+        #[arg(short, long)]
+        /// The key, in hex.
+        key: Option<String>,
+
+        #[arg(long)]
+        /// File containing the key, as raw bytes.
+        key_file: Option<String>,
+
+        #[arg(short, long)]
+        /// Verify against this tag (hex) instead of computing one.
+        verify: Option<String>,
+
+        #[arg(short)]
+        /// Output the tag in hex format.
+        x: bool,
+    },
+
+    /// Perform cSHAKE128 (NIST SP 800-185) of the content provided on stdin. Requires the output
+    /// length in bytes. With no customization string this is exactly SHAKE128.
+    /// Supports streaming update for low memory footprint.
+    CSHAKE128 {
+        /// Length of the output in bytes.
+        length: usize,
+
+        #[arg(short = 's', long)]
+        /// Customization string. Two cSHAKEs with different customization strings produce
+        /// unrelated output, so this domain-separates one use of the function from another.
+        customization: Option<String>,
+
+        #[arg(short = 'n', long)]
+        /// Function-name string. Reserved by NIST for functions it defines (SP 800-185 Sec 3.4);
+        /// use --customization for your own domain separation.
+        function_name: Option<String>,
+
+        #[arg(short)]
+        /// Output the hashes in hex format.
+        x: bool,
+    },
+
+    /// Perform cSHAKE256 (NIST SP 800-185) of the content provided on stdin. Requires the output
+    /// length in bytes. With no customization string this is exactly SHAKE256.
+    /// Supports streaming update for low memory footprint.
+    CSHAKE256 {
+        /// Length of the output in bytes.
+        length: usize,
+
+        #[arg(short = 's', long)]
+        /// Customization string. See cshake128.
+        customization: Option<String>,
+
+        #[arg(short = 'n', long)]
+        /// Function-name string, reserved by NIST. See cshake128.
+        function_name: Option<String>,
+
+        #[arg(short)]
+        /// Output the hashes in hex format.
+        x: bool,
+    },
+
     /// Perform HMAC-SHA256 of the content provided on stdin.
     /// Supports streaming update for low memory footprint.
     /// Note: in production uses, secrets should not be passed on the command-line because they get
@@ -1051,6 +1225,30 @@ fn main() {
         Some(Subcommands::SHAKE256 { length, x }) => {
             sha3_cmd::shake_cmd(256, *length, *x);
         }
+        Some(Subcommands::CSHAKE128 { length, customization, function_name, x }) => {
+            sha3_cmd::cshake_cmd(128, *length, function_name, customization, *x);
+        }
+        Some(Subcommands::TUPLEHASH128 { length, elements, customization, x }) => {
+            sha3_cmd::tuplehash_cmd(128, *length, elements, customization, *x);
+        }
+        Some(Subcommands::TUPLEHASH256 { length, elements, customization, x }) => {
+            sha3_cmd::tuplehash_cmd(256, *length, elements, customization, *x);
+        }
+        Some(Subcommands::PARALLELHASH128 { length, block_size, customization, x }) => {
+            sha3_cmd::parallelhash_cmd(128, *length, *block_size, customization, *x);
+        }
+        Some(Subcommands::PARALLELHASH256 { length, block_size, customization, x }) => {
+            sha3_cmd::parallelhash_cmd(256, *length, *block_size, customization, *x);
+        }
+        Some(Subcommands::KMAC128 { length, customization, key, key_file, verify, x }) => {
+            mac_cmd::kmac_cmd(128, *length, customization, key, key_file, verify, *x)
+        }
+        Some(Subcommands::KMAC256 { length, customization, key, key_file, verify, x }) => {
+            mac_cmd::kmac_cmd(256, *length, customization, key, key_file, verify, *x)
+        }
+        Some(Subcommands::CSHAKE256 { length, customization, function_name, x }) => {
+            sha3_cmd::cshake_cmd(256, *length, function_name, customization, *x);
+        }
         Some(Subcommands::HMAC_SHA256 { key, key_file, verify, x }) => {
             mac_cmd::mac_cmd(HMACVariant::SHA256, key, key_file, verify, *x)
         }