Add de-randomized ML-KEM modes to experimental EVP API #1578
Conversation
Codecov ReportAttention: Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #1578 +/- ##
==========================================
+ Coverage 78.15% 78.16% +0.01%
==========================================
Files 562 562
Lines 94676 94825 +149
Branches 13576 13597 +21
==========================================
+ Hits 73995 74122 +127
- Misses 20084 20108 +24
+ Partials 597 595 -2 ☔ View full report in Codecov by Sentry. |
|
Note: combining into a single PR as per discussions with AWS-LC. The Call-Outs above have been modified to reflect this. |
There was a problem hiding this comment.
left a few comments inline. In general, the most important thing missing is adding the seed length as an input argument to the API and then adding a check that the provided length is correct.
Also, we should now be able to completely get rid of pq_custom_rand_bytes, right? If so, let's delete that code.
Thank you! 333911c addresses these call outs with the exception of how the |
Not just yet, if |
|
For documentation purposes: the Kyber KAT files have been modified so that they output the values of the "coins" generated by the DRBG. These KATs can be generated from the official Kyber repository using To modify the KAT generation file in the same way as I did to output the internal random coins, and thus, see the keygen_coins and encap_coins used to generate the KAT, apply the following patch to |
| *ciphertext_len = kem->ciphertext_len; | ||
| *shared_secret_len = kem->shared_secret_len; | ||
| *seed_len = kem->encaps_seed_len; |
There was a problem hiding this comment.
Thinking about this more, all of these in/out sizes also need null checks before writing to them. Same for keygen.
There was a problem hiding this comment.
Great call out, as the caller will use seed_len as a length check, better make it writable. Added test coverage also for these checks in fa6e270
NIST have made the following public statements regarding the planned changes to FIPS 203: - NIST will specify lower-level de-randomized API to enable CAVP testing with seeds as keys. As such, this PR includes the following: - The addition of ML-KEM-IPD-768 and ML-KEM-IPD-1024 to AWS-LC. *Note*: as common functionality is already added to aws-lc, this lift is extremely light, as we need only to define `crypto/ml_kem/ml_kem_768_ipd.c` and `crypto/ml_kem/ml_kem_1024_ipd.c`. - The addition of de-randomized testing API for ML-KEM-IPD-768 and ML-KEM-IPD-1024 - KATs for ML-KEM-IPD-768 and ML-KEM-IPD-1024 that use seeds as keys (as per CAVP requirement) - An update to the file that captures the divergence from the upstream reference listed at https://github.com/aws/aws-lc/tree/main/crypto/ml_kem#readme. This removes the outdated information regarding `pq_custom_randombytes` and updates with information regarding the de-randomized API. The new KEM algorithms have been added to the `built_in_kems` list, and as such, are included within the complete `PerKEMTest` suite. This includes testing of the de-randomized APIs added in #1578.
Issues:
This is a PR in which we are adding de-randomized modes for ML-KEM. These changes will provide customers with the ability to independently assess the correctness of our ML-KEM implementation through a public API, as well as facilitate upcoming ACVP test vectors (FIPS). These APIs also facilitate the use of ML-KEM in schemes/primitives such as Hybrid Public Key Encryption (HPKE RFC 9180), Messaging Layer Security (MLS RFC 9420), X-Wing (draft-connolly-cfrg-xwing-kem), and batch/multi-recipient KEM
Description of changes:
Today, the KEM API in AWS-LC does not support de-randomized/deterministic modes. As such, known answer testing (KAT) can be difficult to perform. Currently, AWS-LC uses
pq_custom_randombytesto seed, and control internal entropy for testing.As part of the standardisation of ML-KEM in FIPS 203, NIST are outlining the use of de-randomized modes. This PR hooks up the de-randomized APIs for ML-KEM with an experimental EVP APIs
EVP_PKEY_keygen_deterministicandEVP_PKEY_encapsulate_deterministicwithininclude/openssl/experimental.Call-outs:
This is the first in a series of PRs. The overall plan is:
pqcrystals_kyber_ref_common). (complete:1ad9a97)coinsinstead ofseed, we can then removepq_custom_randombytesfrom kyber/ml-kem completely. (complete:1ad9a97 and 333911c) (can't remove completely from the library yet as they are required for dilithium KAT)Testing:
Testing has been added for de-randomized modes within crypto/evp_extra/evp_extra_test.cc.
The testing function is not final, but tests functionality added within this PR. Once subsequent PRs are added, the testing procedure will be condensed with the rest of the KEM tests.
By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license and the ISC license.