[dghgit]

Issue Link

No issue filed yet. This is the prototype behind the key object rework document circulated for review (AES128Key<GCM>, "Death to init()"), opened so the design can be discussed against working code alongside #167.

Summary

Prototype of mode-bound symmetric key objects: AESKey<P, M> and HmacKey<H> are built once from KeyMaterial and produce their encryptors, decryptors, generators and verifiers through role traits in core.

Description

• What: core gains FromKeyMaterial<KEY_LEN> / FromAnyKeyMaterial, the AEAD and MAC role pairs (AeadEncryptionKey / AeadDecryptionKey, the packet pair, MacGenerationKey / MacVerificationKey) and the hazmat Mode<P> traits a mode implements over a permutation. cipher gets GCM, CCM, CMAC and GMAC as mode types over a key state. aes gets one AESKey<P, M> with AES128Key<M> / AES192Key<M> / AES256Key<M> aliases, the forwarding role impls, and a check at construction that the material's KeyType is the one the mode requires (SymmetricCipherKey for the cipher modes, MACKey for CMAC and GMAC), ahead of the permutation's own length and strength checks. There is no algorithm-name binding: KeyMaterial carries no such field, so one KeyMaterial<16> keys AES128Key<GCM>, AES128Key<GCM<12>> and AES128Key<CCM<N, T>> alike, and one MACKey both <CMAC> and <GMAC>. hmac gets HmacKey<H> holding the two pad states, and hkdf one HmacKey per PRK. The aes*-ccm CLI commands and the CCM memory bench run through the key path.
• Why this shape: validation and schedule expansion happen once per key rather than per message; one key under two modes is a compile error; mode-derived state (GCM's H, CMAC's subkeys) lives in the key; and a token-backed key can implement the same role traits, which no constructor taking key bytes allows. The reasoning and the alternatives considered are the document's numbered decisions.
• Alternatives: keeping the static constructors behind the key path, permutation-level keys with the mode as a value, and typed newtypes over KeyMaterial with the constructors kept on the traits (the shape of SymmetricCipherKey: dedicated key types per algorithm #167). Each is discussed in the document.
• Scope of the prototype: AES under GCM, CCM, CMAC and GMAC, plus HMAC. Not yet covered: CBC, CFB, CFB8, CTR and ECB, the other block ciphers, Ascon and ChaCha, KMAC, and removal of the old do_*_init constructors, which stay in place so both routes coexist on this branch.
• Tests: key tests per mode in crypto/aes/tests, CCM and GCM one-shot and packet tests in cipher, HMAC key tests covering keys shorter than, equal to and longer than the block, and the key-type refusals. Every commit builds and passes cargo test --workspace; 1187 tests at the tip.

Scope and Risk

• Packages: core, cipher, aes, hmac, hkdf, sha2, sha3, sm3, core-test-framework, cli, mem_usage_benches. 59 files, +7333 / -1630.
• Runtime behaviour: additive. The existing constructors and one-shots are unchanged; the key path is a second route to the same workers. The HMAC worker no longer carries a key buffer, so HMAC<H> is two hash states.
• Fallibility: quality_stats.sh against the base, unwraps in core code 805 → 818 and Err() 458 → 481: the new fallible one-shots and mode types in cipher and core.
• Regression likelihood: low on existing APIs, since they are not modified; the new path is covered by the tests above and the existing vectors run through it where the CLI does.
• Worst case: a key constructed on the new path accepting material the old route would have refused. The key-type, length and strength checks are tested for the refusals and acceptances.

Validation

cargo build --workspace
cargo test --workspace
cargo test -p bouncycastle-aes aes_key          # key construction, binding and role tests
cargo test -p bouncycastle-hmac hmac_key_tests  # any-length keys
cargo run --release -p mem_usage_benches --bin bench_ccm_mem_usage

Up to date with feature/simple-ciphers: its tip (the CCM do_*_inplace rename, 7084adb) is merged in as 69e24ba, with the rename carried onto the reworked packet type here, and 1185 tests passing on the result.

AI Usage Statement

Did you use AI in creating this pull request:

• No
• Yes, indirectly - no submitted code was generated by AI (e.g., answering questions, performing a review, suggestions, etc.)
• Yes, trivial code changes were generated by AI (e.g., autocompletion of a single line, reformatting, or spell-checking)
• Yes, non-trivial code changes were generated by AI

Assisted-by: Claude:claude-mythos-5-1

[dghgit]

Merged by hand as squash commit.