Feat: AES LightEngine CCM Mode

CLAUDE.md

@@ -136,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

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