Feat: Add ChaCha20, Poly1305, and Chacha20-Poly1305-AEAD

.gitignore

@@ -1,7 +1,23 @@
 Cargo.lock
 **/target
 mutants.out*/
+custom_mutants_output/
 
 
 .idea/
 .vscode/
+
+# editor swap / backup files
+*.swp
+*.swo
+*~
+
+# Claude Code: ignore personal/local state, but share team tooling
+# (skills, slash commands and subagents). settings.json stays local, so personal permission
+# allowlists cannot ride along in a PR.
+.claude/*
+!.claude/skills/
+!.claude/commands/
+!.claude/agents/
+.claude/settings.local.json
+.claude 2/

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

@@ -3,13 +3,20 @@ members = ["cli", "crypto/*", "mem_usage_benches"]
 
 [workspace.package]
 edition = "2024"
+# `bouncycastle-utils` uses `slice::as_chunks`, stable since 1.88; the 2024 edition alone needs 1.85.
+rust-version = "1.88"
 version = "0.1.3"
 
 [workspace.dependencies]
 
 # *** Internal Dependencies ***
 bouncycastle = { path = "./" }
+bouncycastle-aes = { path = "./crypto/aes" }
+bouncycastle-ascon = { path = "./crypto/ascon" }
 bouncycastle-base64 = { path = "./crypto/base64" }
+bouncycastle-chacha20 = { path = "./crypto/chacha20" }
+bouncycastle-chacha20-poly1305-aead = { path = "./crypto/chacha20-poly1305-aead" }
+bouncycastle-cipher = { path = "./crypto/cipher" }
 bouncycastle-core = { path = "crypto/core" }
 bouncycastle-core-test-framework = { path = "./crypto/core-test-framework" }
 bouncycastle-factory = { path = "./crypto/factory" }
@@ -20,9 +27,11 @@ bouncycastle-mlkem = { path = "./crypto/mlkem" }
 bouncycastle-mlkem-lowmemory = { path = "./crypto/mlkem-lowmemory" }
 bouncycastle-mldsa = { path = "./crypto/mldsa" }
 bouncycastle-mldsa-lowmemory = { path = "./crypto/mldsa-lowmemory" }
+bouncycastle-poly1305 = { path = "./crypto/poly1305" }
 bouncycastle-rng = { path = "./crypto/rng" }
 bouncycastle-sha2 = { path = "./crypto/sha2" }
 bouncycastle-sha3 = { path = "./crypto/sha3" }
+bouncycastle-sm3 = { path = "./crypto/sm3" }
 bouncycastle-utils = { path = "./crypto/utils" }
 
 
@@ -41,7 +50,12 @@ version.workspace = true
 edition.workspace = true
 
 [dependencies]
+bouncycastle-aes.workspace = true
+bouncycastle-ascon.workspace = true
 bouncycastle-base64.workspace = true
+bouncycastle-chacha20.workspace = true
+bouncycastle-chacha20-poly1305-aead.workspace = true
+bouncycastle-cipher.workspace = true
 bouncycastle-core.workspace = true
 bouncycastle-factory.workspace = true
 bouncycastle-hex.workspace = true
@@ -51,6 +65,8 @@ bouncycastle-mldsa.workspace = true
 bouncycastle-mldsa-lowmemory.workspace = true
 bouncycastle-mlkem.workspace = true
 bouncycastle-mlkem-lowmemory.workspace = true
+bouncycastle-poly1305.workspace = true
 bouncycastle-rng.workspace = true
 bouncycastle-sha2.workspace = true
 bouncycastle-sha3.workspace = true
+bouncycastle-sm3.workspace = true

QUALITY_AND_STYLE.md

@@ -35,6 +35,8 @@ testing must also be contained within the `mod tests {}` block.
 
 All traits in `bouncycastle-core` must have corresponding tests in `bouncycastle-core-test-framework` that exercise all
 behaviours and error conditions that are common to all implementations of that trait.
+`bouncycastle-core-test-framework` is test infrastructure only: it goes under `[dev-dependencies]` and is never a
+runtime dependency, since it ships a deterministic `FixedSeedRNG`.
 
 All crypto algorithms must have tests against the bc-test-data repo and against wycheproof.
 
@@ -65,7 +67,16 @@ which parts were done for a very specific reason and should not be changed on a
 
 ## Naming Conventions
 
-All normal rust naming convensions from clippy apply. In addition, some library-specific naming conventions:
+All normal rust naming conventions from clippy apply, with one exception:
+
+* Where a type, constant or variable corresponds to something a specification (FIPS, RFC, etc) names, keep the
+  specification's spelling and capitalization, and `#[allow(non_camel_case_types)]`, `#[allow(non_snake_case)]` or
+  `#[allow(non_upper_case_globals)]` the item locally. So the FIPS 204 signature algorithm is `MLDSA65`, not `MlDsa44`,
+  and it's `AES_CBC_128`, not `AesCbc128`, and if a specification writes `A` for a matrix and `a` for a vector then
+  `let A = ...; let a = ...;` is the right thing to do for code readability and correspondence with the spec. The point
+  is that a reviewer with the specification open can match names by eye; that matters more here than rust convention.
+
+In addition, some library-specific naming conventions:
 
 * In constants, "LEN" is the length of a value in bytes (typically used for sizing arrays), whereas "SIZE" is a value in
   bits (typically used as a security parameter). For example SHA256 could have constants `HASH_SIZE = 256` and
@@ -77,7 +88,13 @@ All normal rust naming convensions from clippy apply. In addition, some library-
 ## APIs
 
 Where possible, primitives should expose "one-shot APIs" that simply take data and return a result as a static member
-function that does not require object instantiation.
+function that does not require object instantiation. The exception is anything keyed: a symmetric cipher or MAC is
+reached through a key object (`AES128Key<GCM>`, `HmacKey<SHA256>`, `KMAC128Key`, `AsconAEAD128Key`), built once from
+`KeyMaterial` by `FromKeyMaterial` / `FromAnyKeyMaterial`, and its one-shots and `create_*` constructors are methods on
+that key. The cipher and MAC traits in `core::traits` describe a worker that already exists and carry no constructor
+and no key-taking method, so a key's validation and expansion happen once, where the key is made, rather than per call.
+A worker borrows the key it came from, for the lifetime on the role trait's associated worker type, so making one
+copies no schedule and a worker cannot outlive its key.
 
 Other version of Bouncy Castle have a design pattern where stateful objects follow a pattern of new () -> init () ->
 do_update () -> do_final (), and then optionally reset () that sets the object back to an unitialized state. Instead,
@@ -90,6 +107,64 @@ very little) object state to track and return errors about.
 
 Any struct that holds sensitive data must impl the `core::Secret` trait and all associated super-traits.
 
+A primitive whose safe use depends on the caller composing it correctly -- a raw block permutation, a raw keystream
+-- lives under a `hazmat` module in its crate or sub-module, never at the crate root or next to the safe API;
+`bouncycastle_core::hazmat` defines the term and the supported uses. A crate or sub-module with such items declares
+`pub mod hazmat;`
+in its `lib.rs` and neither the crate nor the sub-module ever `pub use`s anything out of it, since a re-export would
+bypass the notice.
+
+Any function that writes into a caller-provided output buffer must report how many bytes it wrote, as a `usize` in
+its `Ok` value (on its own, or alongside anything else the function needs to return, such as a generated IV). This
+holds even when the count is fully determined by the input -- a fixed-length `[u8; LEN]` buffer, say, always writes
+exactly `LEN` -- so that callers never have to remember which output-buffer methods report their length and which
+don't.
+
+### fn prefixes and suffixes
+
+Function prefixes and suffixes are used consistently across the library.
+
+Take, for example a one-shot API `fn encrypt(plaintext: &[u8]) -> Result<Vec<u8>, SymmetricCipherError>`.
+
+The following prefixes can be applied:
+
+* `do_`: this implies that it is part of a stateful streaming API, will typically take `&mut self`, and is likely
+  accompanied by a `do_encrypt_final()`; the object comes from a key's `create_encryptor()`.
+* `create_`: a key object's constructor for a worker -- `create_encryptor(&self, rng)`, `create_decryptor(&self,
+  init_data)`, `create_generator(&self)`, `create_verifier(&self)`. Whatever draws randomness takes a `&mut dyn RNG`
+  explicitly, so a key has no `_rng` twins and no method that reaches for a default RNG.
+
+The following suffixes can be applied
+
+* `_update / _final`: indicates phase of a stateful streaming API. Other verbs can be used here as appropriate to the
+  primitive, such as `absorb / squeeze`, `encrypt / decrypt`, etc. `_final` indicates that this function call renders
+  the object unusable afterwards by consuming `self` via a move: `_final(self, ..)`.
+* `_rng`: indicates that this version of the function sources its random numbers from a provided `&mut dyn RNG` instead
+  of from the default library RNG. `_rng(.., &mut dyn RNG)`. Keyed primitives do not have it: their constructors and
+  one-shots take the RNG, full stop.
+* `_nonce`: on an AEAD key, the twin that takes the nonce from the caller instead of drawing it from the RNG, and so
+  does not return one.
+* `_out / _inplace`: indicates that the function works in the provided buffer. `_out` indicates that the function takes
+  an output buffer, which may be oversized, and returns the number of bytes written to it:
+  `_out(.., out: &mut [u8] -> Result<usize, SymmetricCipherError>`. `_inplace` indicates that the input and output are
+  required to be the same size, and so the function uses the same buffer for input and output:
+  `_inplace(.., data: &mut [u8]) -> Result<usize, SymmetricCipherError>`. It is assumed that these will be
+  memory-efficient and work in the provided buffer instead of creating duplicate data on the stack.
+* `_out_len`: a pair for an `_out` function that computes the minimum size of the output buffer required for the paired
+  `_out` function to succeed. This may be an over-estimate in order to guarantee success, for example if the size of the
+  required output buffer depends on the contents, and a subsequent call to the paired `_out` function does not actually
+  fill all of the requested space.
+
+Where multiple suffixes are present on a single function, they should go in this order:
+
+```text
+_{init, update, final, etc}_{rng}_{out, out_len, inplace}
+```
+
+Any function that takes an output buffer via an `_out` function must zeroize the provided output buffer via a
+`out.fill(0)` prior to writing to it. This must be done first, before even any error checking so that no stale content
+is left in the output buffer, even in the case of an error.
+
 ## Fallibility
 
 As much as humanly possible, Result and unwrap () should be used for "Bad input data" type things and not "Programmer
@@ -130,8 +205,55 @@ Note that rust macros tend not to play well with a lot of dev tooling for compil
 `cargo mutants`, which is a good reason to avoid macros in core algorithm or data processing code. Macros can be used
 more freely within test code.
 
+## Unit tests vs integration tests
+
+Unit tests are test code (and supporting helper functions) embedded in src/**.rs files. They have access to
+crate-private or module-private functions and constants.
+
+Integration tests are test code (and supporting helper functions) in tests/**.rs files. They test the crate's code from
+the outside -- ie through its public APIs -- since tests/ is a separate crate from src/.
+
+In general, integration tests are preferred over unit tests. This is for a number of reasons:
+
+* To reduce reviewer burden; reviewers will typically focus more effort on the src/ than the tests/, so we want to keep
+  src/ as short as is reasonable.
+* Usually it is easier to determine what is the correct behaviour at the public API level. For example, this is the
+  level at which we typically have KATs and test vectors.
+* Tools like cargo mutants are very helpful at detecting branches that are not exercisable via the public APIs, which
+  often is an indicator that the branch isn't doing what you think it's doing, or is simply not useful and can be
+  deleted. Unit tests that bypass the public APIs to pin these sorts of branches obscure the fact that this code is
+  unreachable.
+
+Unit tests are reasonable to include in the following cases:
+
+* There is high-risk code (usually meaning that it is complex code whose behaviour is not obvious from inspection) where
+  unit tests help to document the behaviour and protect against accidental breakage via a benign-looking change.
+* AND where known answer tests are available.
+* AND where this behaviour cannot be tested from integration tests.
+
+When writing unit tests, they should be contained with an `mod tests` at the bottom of the file, and ALL helper
+functions that support the unit tests must be contained within that module. The intention is to clearly signal to a code
+reviewer what is test code vs functional code.
+
 # Docs
 
+## Proportion
+
+Docs are a reading cost, so default to short. Each fact has one home: the crate docs are an overview plus links, and
+the detail lives on the type or module it describes. Rationale is a sentence or two next to the code; history and
+derivations go in the commit message. Give a few examples, not one per variant; keep memory tables to the figures,
+without a per-row essay; keep CLI docs out of library crates; and never repeat a spec quote across files. Before adding
+material, check whether the crate already states it.
+
+## No internal implementation detail in public API docs
+
+The doc comment on a `pub` item is read by a calling application, so it says what the caller can observe and must
+do: the contract, the buffers and lengths involved, the errors and when they occur. How the implementor meets that
+contract -- which bytes it holds back and why, which private helper runs, how another implementor does it, the design
+rationale for a trait's shape -- belongs in a `//` comment next to the code, on the private item, or in the commit
+message. A trait's docs in particular describe the trait, not any one implementor. When reviewing, read each public
+doc comment as a user with no access to the source and strike anything that only makes sense with it.
+
 ## Usage Examples
 
 The crate docs needs a section "Usage Examples" with sample code for all the major usage patterns of the primitives in
@@ -146,4 +268,12 @@ the crate.
 
 Most crates should have a "Security Considerations" section that documents any footguns where the user of this crate
 could undermine their own security; for example where providing a seed or a nonce that is not truly random would
-completely undermine the algorithm.
+completely undermine the algorithm.
+
+The heading is always exactly `# 🚨 Security Considerations 🚨`, wherever it appears: crate docs, module docs, or the
+docs of an individual type or function. A consistent heading makes these sections easy to spot when reading and to find
+with a search.
+
+## Release Notes
+
+For release note entries, keep succinct, one line per significant change at most.

alpha_0.1.3_release_notes.md

@@ -2,8 +2,38 @@
 
 ## Major features
 
+* 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_CCM, AES_CFB, AES_CFB8, AES_CTR, and AES_GCM.
+    * ASCON -- Ascon-AEAD128, Ascon-Hash256, Ascon-XOF128 and Ascon-CXOF128 (NIST SP 800-232).
+    * CHACHA20 -- ChaCha20, Poly1305 and ChaCha20-Poly1305 (RFC 8439).
+* Further memory usage improvements on ML-DSA / ML-KEM. New figures for the largest size are:
+    * ML-DSA-87/Sign 118 kb, ML-DSA-87/Verify 212 kb
+    * ML-DSA-87_lowmemory/Sign 25 kb, ML-DSA-87_lowmemory/Verify 21 kb
+    * ML-KEM-1024/Encaps 44 kb, ML-KEM-1024/Decaps 58 kb
+    * ML-KEM-1024_lowmemory/Encaps 11 kb, ML-KEM-1024/Decaps 21 kb
+    * Performance (throughput) actually saw a slight performance increase as this cleanup was largely about finding and
+      removing unnecessary memcpy's.
+
 ## Minor features / bug fixes
 
-* bug fixes to the way SHA3/SHAKE handled absorbing and squeezing a partial final byte.
 * Design discussions about whether core::traits::XOF (in the abstract) should allow interleaving absorb -> squeeze ->
-  absorb (ie "absorb-after-squeeze). Outcome: absorb-after-squeeze forbidden. Could be changed in the future.
+  absorb (ie "absorb-after-squeeze). Outcome: absorb-after-squeeze forbidden. Could be changed in the future. Refactored
+  to an `XOF::xof()`, `XOF.into_squeezer()`, 'XOFSqueezer.output ()' shape.
+* SHA2:
+    * Implemented SHA512/224 and SHA512/256.
+    * `Hash::do_final_partial_bits()` / `do_final_partial_bits_out()` are now implemented for SHA-2 (FIPS 180-4 s. 5.1).
+* SHA3:
+    * Fixed a bug in `XOF::squeeze_partial_byte_final()`: when it was the first squeeze it bypassed the SHAKE `1111`
+      domain suffix and returned raw Keccak output, and it returned the wrong `num_bits` bits of the output byte.
+    * Changed the order of bits when absorbing a final partial byte to match ASN.1 DER BIT_STRING bit ordering.
+* The constant-time helpers in bouncycastle-utils now use a more robust optimization barrier based on unsafe
+  `read_volatile` / `write_volatile` instead of `core::hint::black_box`, which is documented as best-effort only.
+* Added the `hazmat` module convention for primitives whose safe use is the caller's job; `bouncycastle_core::hazmat`
+  defines it.
+    * The `do_hazardous_operations` handler for `KeyMaterial` is now `hazmat`.
+    * ML-KEM `encaps_internal` is now `hazmat::EncapsWithRandomness::encaps_with_randomness`, and
+      `HashDRBG80090A::new_unititialized` is `hazmat::NewUninitialized::new_uninitialized` (typo fixed); both are
+      extension traits, so the call needs the `hazmat` import.
+    * New cipher-related features `ElectronicCodeBook`, `KeyStream`, the `AES*Internal` types, `Ecb` and `AES_ECB_*`,
+      and `CtrKeyStream` under their crates' `hazmat` modules.