Feat: Implement ASCON Lightweight Cryptographic Libraries

[officialfrancismendoza]

Description

Implementation of NIST SP 800-232 ASCON lightweight cryptography standards for constrained devices (#22), including:

• Authenticated Encryption (aead128)
• Hashing (hash256)
• Extendable Output Functions (xof128)
• Custom Extendable Output Functions (cxof128)

Note: due to the important considerations of embedded systems, this PR must follow, where applicable, utilization of non-heap memory structures (for example: [u8, CONST_SIZE] instead of vec) to respect their compute and RAM limitations.

Type of Change

• Changes to core crate, affecting traits
• A new ASCON crate with associated src files and testing suite

A full list of detailed changes are outlined in the crate's summary.md file.

Testing

• cargo test -p bouncycastle-ascon to test ASCON crate and associated KAT test cases
• cargo test --workspace
• cargo mutants --package bouncycastle-ascon for mutant tests

Important TBDs for testing:

• Implement Crucible testing
• Implement Wycheproof tests

[ounsworth]

@officialfrancismendoza I see this. On my todo list!

[jjkurczak]

@officialfrancismendoza, a couple things on this one so far:

1. cargo mutants is seeing 124 missed mutations - it's hard for me to judge how many of them are legitimate, but is this similar to the volume you were seeing yourself?
2. I'm seeing your .claude/settings.json being pushed into the repo, might be worth using https://git-scm.com/docs/gitignore to keep this out of commits automatically?

[ounsworth]

First review:

This PR is currently failing the rustfmt check. Just run $ cargo fmt in the root and commit again.

The Crucible project only has tests for ML-KEM and ML-DSA. So does not apply here.

There are ascon vectors in both Wycheproof and bc-test-data, so you should be able to take the test harnesses that we have in, for example, ml-dsa and port that over for ascon.

(I will continue with a code review, though I admit that +3,900 is a lot to review, so I will have to do this in chunks.)

[ounsworth]

This file seems maybe like it is your personal notes that were checked in by accident? I don't see any long-term value in including this file in the source code.

[ounsworth]

I like this point and I think it should be expanded. I'm thinking something like:

Decryption tag check failure: a ciphertext decryption whose finalization returns an Err(AuthenticationFailed) should be considered to be tampered with and the entire plaintext should be rejected. For example, if the plaintext being decrypted is large enough that it must be processed by the application in a streaming fashion, the application should have a way to cancel the operation or transaction with an error if ASCON finalization returns an AuthenticationFailed error.

[ounsworth]

The rest of the library uses do_final_out() for this pattern. I actually kinda like _into instead of _out, but one way or another this should be made consistent with the rest of the library.

If you think that _into is the better name, than why don't you open a github issue to propose that change, and then create a PR against 0.1.3alpha.

[ounsworth]

Why is this not a KeyMaterial?

[ounsworth]

This API pattern seems extremely weird to me.
First the user has to create a mut vec of the correct size plaintext.len() + 16.
Then the user has to hand that in to the encrypt function.
Then the user has to truncate it because it might actually be shorter than plaintext.len() + 16 ?

I might expect some acrobatics like that in no_std where the user has to hand in a [u8; N] of the correct size, but the whole point of Vec's is to avoid making the user deal with array lengths.
If we're using vec here, then can't we hide this inside the function call and -> Vec<u8> that we size correctly?

[ounsworth]

All the ASCON variants should impl traits::Algorithm and maybe traits::HashAlgParams?

[ounsworth]

Claude likes to leave comments like these explaining its reasoning. That's fine for you to understand what it's done, but should be deleted before committing.

[ounsworth]

I assume that this function should correspond to Algorithm 2 in SP.800-232.
I would like you to use a commenting style similar to what I have done in ML-DSA to make it clear how our code corresponds with the sample code in SP.800-232.
For example:
https://github.com/bcgit/bc-rust/blob/main/crypto/mldsa/src/aux_functions.rs#L15

Moreover, for larger functions, I actually comment line-by-line with the corresponding line numbers in the FIPS sample algorithms to make the correspondence super clear, especially if our code is skipping steps or doing steps out-of-order.
Some examples:
https://github.com/bcgit/bc-rust/blob/main/crypto/mldsa/src/aux_functions.rs#L435
https://github.com/bcgit/bc-rust/blob/main/crypto/mldsa/src/mldsa.rs#L929

This also provides a way to note any deviations that we are making from the FIPS, which will make certification easier.
Example:
https://github.com/bcgit/bc-rust/blob/main/crypto/mldsa/src/mldsa_keys.rs#L665

But actually, looking closer, this does not appear to be the same as Algorithm 2, this is generating the padding string 1 || 0^j but not performing the concatenation. So then it is confusing to give it the same name as Alg 2.

Possibly, this indicates that in fact this code does not correspond directly to the FIPS sample algorithms and we should do a refactor so that it does?

[ounsworth]

This function exists verbatim in both ascon_xof128.rs and ascon_cxof128.rs. That means that some de-duplication should be done.

I would suggest doing some re-structuring of this code to better match the structure suggested by SP.800-232:

• Have an aux_functions.rs that corresponds to SP.800-232 section 2.1 which includes Algorithm 1 parse(X, r) and Algorithm 2 pad(X, r), and then also serves as a logical place to put other code that will be common to the various parts of ACSON.
• Maybe create permutation.rs that corresponds with SP.800-232 and contains the implementations of 𝐴𝑠𝑐𝑜𝑛-𝑝[8] and 𝐴𝑠𝑐𝑜𝑛-𝑝[12]. I would expect to see this as a single parametrized function to avoid duplicate code, reduce code-review burden, and reduce number of tests needed.

[ounsworth]

I assume this encrypt_out function is supposed to correspond to Algorithm 3 Ascon-AEAD128.enc(𝐾, 𝑁 , 𝐴, 𝑃 ) from SP.800-232?

A few things that catch my eye on a first look:

• This should match exactly the API of Algorithm 3, including the name enc enc_out instead of encrypt / encrypt_out. I would also make the names of the inputs K, N, A, P match exactly.
• A header comment in the same style as, for example, this indicating that this is the implementation of Algorithm 3.
• Algorithm 3 has 4 inputs, but this only has 3. I see that you are not allowing the user to provide the nonce, but instead you are forcing them to use our HashDRBG_SHA512::new_from_os() (via the Self::fresh_nonce() call). This will be problematic, for example, in environments that can't use our RNG and need to connect in for example a hardward RNG. I think we should match exactly the API of FIPS Algorithm 3. If you want, you could do
  N: Option<&[u8; NONCE_LEN]> (or maybe that should be a KeyMaterial?) and if it's None then we can generate it for the user. I've done similar patterns in ML-DSA / ML-KEM.
  You should also provide an enc_rng similar to what I've done with MLKEM.encaps_rng that takes an &mut dyn RNG and uses that for sourcing entropy.
• The name of the constant CRYPTO_KEYBYTES is confusing. I think this should be KEY_LEN to be consistent with other similar constants across the library (I use "LEN" for a length in bytes, and "SIZE" for lengths in bits. This is described in the QUALITY_AND_STYLE.md. Same goes for CRYPTO_ABYTES.
• At a quick glance, the body of this function does not look anything like the the body of Algorithm 3; I think because you have chopped up Algorithm 3 into a new(), update(), final() streaming pattern, which is fine, but you'll need to heavily comment all of the involved functions to make the correspondence with the FIPS Algorithms clear.
• By the way, the rest of the library uses _final() not _finalize().
• Algorithm 3 returns Output: ciphertext 𝐶, 128-bit tag 𝑇. You are returning the nonce, and it doesn't look like you're returning the tag at all. This doesn't make sense to me.