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

CLAUDE.md

@@ -69,9 +69,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`:
 
@@ -130,7 +136,11 @@ Repo mechanics behind those rules, which the documents don't spell out:
 - `./dev_scripts/quality_stats.sh` produces the fallibility metrics both documents ask you to check. Run it before
   and after a change and compare, rather than eyeballing the diff.
 - **CLI commands stream.** The `cli/` binary is stdin→stdout with ~1 KB buffers so commands compose in shell
-  pipelines; preserve that when adding subcommands.
+  pipelines; preserve that when adding subcommands. The exception is a construction that is not
+  itself streamable, such as CCM (SP 800-38C Sec 3: "CCM is not designed to support partial
+  processing or stream processing", because the payload length is inside the first block the MAC
+  covers) -- there, read the whole input once and process it in place, rather than adding a second
+  buffer the size of the input on top of it; see `aes_ccm_cmd.rs`.
 - Trait → factory → CLI is the wiring path for a new primitive; see [the workspace architecture](#the-core--core-test-framework--factory-spine) above for the crates involved.
 
 ## Scope of changes
@@ -180,7 +190,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.

CONTRIBUTING.md

@@ -43,10 +43,10 @@ Some specifics:
 * Public APIs of a library should be both ergonomic and expressive. When defining a new trait or public function, ask
   yourself whether a programmer who is new to cryptography is likely to use this in a way that will get them into
   trouble.
-* Variables should be well-named, well-structured, and well-commented (a comment-to-code ration of 1:1 is a goal to be
+* Variables should be well-named, well-structured, and well-commented (a comment-to-code ratio of 1:1 is a goal to be
   strived for!). Think about memory footprint and, where possible, use unnamed scopes to allow the compiler to pop
   intermediate value variables off the stack as soon as they are no longer needed.
-* Always run your code through `cargo mutants` and get the issue count as low as your can. As a first pass, this forces
+* Always run your code through `cargo mutants` and get the issue count as low as you can. As a first pass, this forces
   you to write thorough unit tests. As a second pass, this draws your attention to bits of your code that cannot be
   tested from the outside. Often this means that the code can be simplified without affecting functionality (as defined
   by your set of unit tests) -- "simpler code" usually means faster runtime and easier future maintenance.
@@ -71,7 +71,7 @@ For minor updates, you can instead choose to create an issue with short snippets
 
 * For contributions touching multiple files try and split up the pull request, smaller changes are easier to review and
   test, as well as being less likely to run into merge issues.
-* Create a test cases for your change, it may be a simple addition to an existing test. If you do not know how to do
+* Create test cases for your change; it may be a simple addition to an existing test. If you do not know how to do
   this, ask us and we will help you.
 * If you run into any merge issues, check out this [git tutorial](https://github.com/skills/resolve-merge-conflicts) to
   help you resolve merge conflicts and other issues.

Cargo.toml

@@ -10,6 +10,7 @@ version = "0.1.3"
 # *** Internal Dependencies ***
 bouncycastle = { path = "./" }
 bouncycastle-aes = { path = "./crypto/aes" }
+bouncycastle-ascon = { path = "./crypto/ascon" }
 bouncycastle-base64 = { path = "./crypto/base64" }
 bouncycastle-modes = { path = "./crypto/modes" }
 bouncycastle-core = { path = "crypto/core" }
@@ -46,6 +47,7 @@ edition.workspace = true
 
 [dependencies]
 bouncycastle-aes.workspace = true
+bouncycastle-ascon.workspace = true
 bouncycastle-base64.workspace = true
 bouncycastle-core.workspace = true
 bouncycastle-factory.workspace = true

alpha_0.1.3_release_notes.md

@@ -5,6 +5,46 @@
 * New algorithms added to crypto/ :
     * SM3 -- the SM3 hash (GB/T 32905-2016 / ISO/IEC 10118-3:2018), ported from bc-java.
     * AES -- AES-128/192/256, along with its modes AES_ECB, AES_CBC, AES_GCM.
+    * ASCON -- Ascon-AEAD128, Ascon-Hash256, Ascon-XOF128 and Ascon-CXOF128 (NIST SP 800-232).
+      `AsconAead128Encryptor` / `AsconAead128Decryptor` implement the generated-nonce
+      `AEADCipherEncryptor` / `AEADCipherDecryptor` pair; the inherent `AsconAead128` API keeps the
+      explicit-nonce, in-place streaming form (`new_encrypting` / `new_decrypting`).
+      `Ascon_AEAD128<Dir>` names the pair by direction (`Ascon_AEAD128<Encrypting>` /
+      `Ascon_AEAD128<Decrypting>`).
+    * `bouncycastle-ascon` is re-exported as `bouncycastle::ascon`; `Ascon-Hash256` and
+      `Ascon-XOF128` are registered in the factories, and the CLI adds `ascon-hash256`,
+      `ascon-xof128`, `ascon-cxof128` and `ascon-aead128`. The AEAD command generates and prefixes
+      the nonce by default, with `--nonce`/`--nonce-file` retained for deterministic vectors.
+      Streaming decrypt releases plaintext before the final tag check, so callers must discard any
+      output if finalization or the CLI exit status reports authentication failure.
+* `core` gains the streaming AEAD split: `AEADCipherEncryptor<KEY_LEN, NONCE_LEN, TAG_LEN,
+  FINAL_LEN>` and `AEADCipherDecryptor<...>`, which extend `SymmetricCipherEncryptor<KEY_LEN,
+  NONCE_LEN, FINAL_LEN>` / `SymmetricCipherDecryptor<...>`. The inherited methods are the AEAD
+  with no associated data and the tag inline (`ciphertext || tag`), so an AEAD can be held and
+  used as a plain symmetric cipher; `FINAL_LEN` is the tag plus anything the cipher holds back,
+  and every decryptor holds back the last `TAG_LEN` bytes it has seen, since it cannot know which
+  layout its final call will ask for. The AEAD traits add `do_update_aad`; the detached-tag
+  methods, each named for the base method it mirrors plus `_detached` (`do_final_detached` /
+  `do_final_out_detached`, `encrypt_out_detached`, `encrypt_out_rng_detached`, `encrypt_detached`,
+  `decrypt_out_detached`, `decrypt_detached` and the `*_len_detached` sizing helpers); and the
+  inline-tag one-shots with AAD, named for their base method plus `_with_aad`
+  (`encrypt_out_with_aad`, `encrypt_out_rng_with_aad`, `encrypt_with_aad`, `decrypt_out_with_aad`,
+  `decrypt_with_aad`).
+  `SymmetricCipherDecryptor::decrypt_out` now zeroizes what it wrote when `do_final` fails, as the
+  AEAD one-shots always have.
+  The older single-type `core::traits::AEADCipher`, which this splits and which had no
+  implementors, is removed, along with its `core-test-framework` suites
+  (`TestFrameworkAEADCipher::test` / `::test_plain_one_shots`).
+  Mutation testing of the pair's defaults (`traits.rs`, scoped to `AEADCipher{En,De}cryptor` and
+  `SymmetricCipherDecryptor::decrypt_out`, tested through `bouncycastle-core` +
+  `bouncycastle-ascon`) reports 134 mutants, 107 caught, 27 unviable and none missed; the
+  `AsconAead128Encryptor` / `AsconAead128Decryptor` adapters report 76 mutants, 49 caught, 27
+  unviable and none missed.
+* ASCON testing covers the NIST LWC KAT sweeps from `bc-test-data` (1089 AEAD128, 1025 Hash256,
+  1025 XOF128 and 1089 CXOF128 cases when the data repository is present), plus embedded always-on
+  vectors. Mutation testing for `bouncycastle-ascon` reports 661 mutants, 558 caught, 97 unviable
+  and 6 missed; the six survivors are the sponge boundary and `set_state_byte` OR/XOR equivalences
+  documented at their sites.
 
 ## Minor features / bug fixes
 

cli/src/aead_mode_cmd.rs

@@ -0,0 +1,184 @@
+//! Shared plumbing for the AEAD subcommands: `aes{128,192,256}-gcm`.
+//!
+//! Parallel to [`crate::stream_mode_cmd`], but for [`bouncycastle::modes::Gcm`] rather than a
+//! [`StreamCipherEncryptor`](bouncycastle::core::traits::StreamCipherEncryptor) mode: GCM carries
+//! additional authenticated data and a tag, neither of which that trait has room for, so this
+//! module drives it through [`AEADCipherEncryptor`] / [`AEADCipherDecryptor`] instead, which add
+//! `do_update_aad` to the symmetric-cipher streaming methods.
+//!
+//! # On-the-wire format: `nonce || ciphertext || tag`
+//!
+//! `encrypt` writes the generated 12-byte nonce first, then the ciphertext as it streams, then the
+//! 16-byte tag once stdin is exhausted. `decrypt` reads the 12-byte nonce first, then streams the
+//! rest of stdin through the inline decryptor -- which, per [`SymmetricCipherDecryptor`]'s contract,
+//! holds back the last 16 bytes it has seen because they might be the tag -- and checks the tag on
+//! `do_final`.
+//!
+//! # The exit code is the signal, not the output
+//!
+//! On a tag failure, `decrypt` has **already written plaintext to stdout**: the inline decryptor
+//! releases bytes as they clear the tail hold-back, well before the tag at the very end of the
+//! stream can be checked. This is the same trade-off `Gcm`'s streaming API documents; a script that
+//! needs to know before acting on the output must use the one-shot instead (not exposed by this
+//! CLI) or check the exit code before trusting anything already written. On failure this command
+//! prints `Error: authentication failed` to stderr and exits non-zero.
+//!
+//! # AAD
+//!
+//! `--aad <hex>` or `--aad-file <path>`; if neither is given, AAD is empty. Fed to the engine in
+//! one call before any ciphertext, matching SP 800-38D Algorithm 4's requirement that AAD precede
+//! data.
+//!
+//! `--aad-file` is read as raw bytes ([`read_from_file_raw`]), never hex-decoded. The
+//! hex-or-raw guess `--key-file` uses would change what is authenticated without any error: a
+//! binary header that happens to parse as hex text (`cafe`, or sixteen zero bytes, which the hex
+//! decoder skips) would be authenticated as its decoding, and the tag would not verify against any
+//! other GCM implementation given the same file.
+
+use crate::helpers::{read_from_file_raw, write_bytes_or_hex};
+use bouncycastle::core::key_material::KeyMaterial;
+use bouncycastle::core::traits::{
+    AEADCipherDecryptor, AEADCipherEncryptor, ElectronicCodeBook, SymmetricCipherDecryptor,
+    SymmetricCipherEncryptor,
+};
+use bouncycastle::hex;
+use bouncycastle::modes::{Decrypting, Encrypting, Gcm};
+use std::io;
+use std::io::{Read, Write};
+use std::process::exit;
+
+/// Bytes read from stdin per call. GCM has no batching advantage from a larger chunk the way CTR's
+/// four-block path does, so this matches the other streaming commands' 1 KiB rather than needing
+/// its own tuning.
+const CHUNK_LEN: usize = 1024;
+
+/// Loads the additional authenticated data from `--aad` (hex) or `--aad-file` (raw bytes; see the
+/// module docs for why not hex). Empty if neither is given: AAD is optional, unlike the key.
+pub(crate) fn load_aad(aad: &Option<String>, aad_file: &Option<String>) -> Vec<u8> {
+    if let Some(path) = aad_file {
+        read_from_file_raw(path)
+    } else if let Some(hex_str) = aad {
+        hex::decode(hex_str).unwrap_or_else(|_| {
+            eprintln!("Error: `--aad` must be hex. Use `--aad-file` for raw bytes.");
+            exit(-1);
+        })
+    } else {
+        Vec::new()
+    }
+}
+
+/// Encrypts stdin to stdout under GCM: writes the generated nonce, then the ciphertext as it
+/// streams, then the tag.
+pub(crate) fn encrypt_gcm<P, const KEY_LEN: usize, const TAG_LEN: usize>(
+    key: &KeyMaterial<KEY_LEN>,
+    aad: &[u8],
+    output_hex: bool,
+) where
+    P: ElectronicCodeBook<KEY_LEN, 16>,
+{
+    let (mut enc, nonce) = Gcm::<P, Encrypting, KEY_LEN, TAG_LEN>::do_encrypt_init(key)
+        .unwrap_or_else(|e| {
+            eprintln!("Error: couldn't start encryption: {e:?}");
+            exit(-1);
+        });
+    write_bytes_or_hex(&nonce, output_hex);
+
+    enc.do_update_aad(aad).unwrap_or_else(|e| {
+        eprintln!("Error: couldn't absorb the additional authenticated data: {e:?}");
+        exit(-1);
+    });
+
+    let mut buf = [0u8; CHUNK_LEN];
+    let mut out = [0u8; CHUNK_LEN];
+    loop {
+        let n = io::stdin().read(&mut buf).unwrap_or_else(|e| {
+            eprintln!("Error: failed to read from stdin: {e}");
+            exit(-1);
+        });
+        if n == 0 {
+            break;
+        }
+        // GCM's encryptor holds nothing back, so `out` (as long as `buf`) always has room.
+        let written = enc.do_update_out(&buf[..n], &mut out).unwrap_or_else(|e| {
+            eprintln!("Error: encryption failed: {e:?}");
+            exit(-1);
+        });
+        write_bytes_or_hex(&out[..written], output_hex);
+    }
+
+    // The detached final flushes nothing for GCM and returns the tag, written last.
+    let (_, _, tag) = enc.do_final_detached().unwrap_or_else(|e| {
+        eprintln!("Error: encryption failed: {e:?}");
+        exit(-1);
+    });
+    write_bytes_or_hex(&tag, output_hex);
+    finish(output_hex);
+}
+
+/// Decrypts stdin to stdout under GCM: reads the 12-byte nonce, streams the rest through the
+/// inline decryptor, and checks the tag on `do_final`. See the module docs for why plaintext may
+/// already be written to stdout by the time a tag failure is reported.
+pub(crate) fn decrypt_gcm<P, const KEY_LEN: usize, const TAG_LEN: usize>(
+    key: &KeyMaterial<KEY_LEN>,
+    aad: &[u8],
+    output_hex: bool,
+) where
+    P: ElectronicCodeBook<KEY_LEN, 16>,
+{
+    let mut nonce = [0u8; 12];
+    if let Err(e) = io::stdin().read_exact(&mut nonce) {
+        eprintln!(
+            "Error: input too short to contain the 12-byte nonce that `encrypt` writes first ({e})."
+        );
+        exit(-1);
+    }
+
+    let mut dec = Gcm::<P, Decrypting, KEY_LEN, TAG_LEN>::do_decrypt_init(key, &nonce)
+        .unwrap_or_else(|e| {
+            eprintln!("Error: couldn't start decryption: {e:?}");
+            exit(-1);
+        });
+    dec.do_update_aad(aad).unwrap_or_else(|e| {
+        eprintln!("Error: couldn't absorb the additional authenticated data: {e:?}");
+        exit(-1);
+    });
+
+    let mut buf = [0u8; CHUNK_LEN];
+    loop {
+        let n = io::stdin().read(&mut buf).unwrap_or_else(|e| {
+            eprintln!("Error: failed to read from stdin: {e}");
+            exit(-1);
+        });
+        if n == 0 {
+            break;
+        }
+        let out_len = dec.update_out_len(n);
+        let mut out = vec![0u8; out_len];
+        dec.do_update_out(&buf[..n], &mut out).unwrap_or_else(|e| {
+            eprintln!("Error: decryption failed: {e:?}");
+            exit(-1);
+        });
+        write_bytes_or_hex(&out, output_hex);
+    }
+
+    if let Err(e) = dec.do_final() {
+        // Whatever plaintext was already written above stands; the exit code is the signal a
+        // script must check (see the module docs).
+        io::stdout().flush().ok();
+        eprintln!("Error: authentication failed: {e:?}");
+        exit(-1);
+    }
+
+    finish(output_hex);
+}
+
+/// Flushes stdout, and adds the trailing newline the hex-output commands all emit.
+fn finish(output_hex: bool) {
+    if output_hex {
+        println!();
+    }
+    io::stdout().flush().unwrap_or_else(|e| {
+        eprintln!("Error: failed to flush stdout: {e}");
+        exit(-1);
+    });
+}