-
Notifications
You must be signed in to change notification settings - Fork 119
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Adding NISTDSA API to support ML-DSA-44 and ML-DSA-87 #1949
Conversation
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #1949 +/- ##
==========================================
+ Coverage 78.68% 78.75% +0.06%
==========================================
Files 585 590 +5
Lines 100854 101428 +574
Branches 14298 14383 +85
==========================================
+ Hits 79357 79876 +519
- Misses 20863 20917 +54
- Partials 634 635 +1 ☔ View full report in Codecov by Sentry. |
int (*sign)(uint8_t *sig, size_t *sig_len, | ||
const uint8_t *message, | ||
size_t message_len, | ||
const uint8_t *ctx, |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
what's ctx
?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
ctx
was added to all NIST PQC candidates in the final version of the FIPS standards. It is a context string (byte string 255 or fewer bytes) that is used as additional input when signing. See page 17 of FIPS 204.
extern "C" { | ||
#endif | ||
|
||
// NISTDSA_METHOD structure and helper functions. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think we should change the name NISTDSA, maybe to NIST_PQDSA or something like that.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Happy to change the name -- originally wanted to use DSA but it was taken. I chose to add NIST
because of the consistency between the FIPS 204, 205 standards, it seems as though any subsequent signature scheme standardizaed by NIST should follow these conventions. I didn't want to limit this to only signature schemes aimed towards PQ-secure use-cases.
crypto/dilithium/internal.h
Outdated
size_t keygen_seed_len; | ||
size_t sign_seed_len; | ||
const NISTDSA_METHOD *method; | ||
const EVP_PKEY_ASN1_METHOD *asn1_method; |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
why do you need the asn1 method within this struct?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Good catch, not used, fixed in 465d53f
crypto/dilithium/kat/mldsa44.txt
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
where are the KATs from?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
These KATs are from the official upstream repository (https://github.com/pq-crystals/dilithium). They were generated the same way the ML-DSA-65 KATs were generated, from the reference.
if (key->priv == NULL) { | ||
goto err; | ||
} | ||
static const uint8_t kOIDMLDSA44[] = {0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04, 0x03, 0x11}; |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
please add reference for these ids
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
added in 465d53f
Splitting this PR up further, first part adds the functionality to support multiple parameter sets of ML-DSA and other NIST PQC DSA (#1963). The second PR will add ML-DSA-44 and ML-DSA-87. |
Issues:
Resolves #CryptoAlg-2725
Description of changes:
This is a sizable PR, I've worked extremely hard to keep the size down in a single PR, but with ML-DSA touching X.509, PKEY, ASN1, there are a lot of changes that need to happen simultaneously to preserve library functionality, so I will document this PR well.
1. PKEY structure changes
This PR adds ML-DSA-44 and ML-DSA-87 to AWS-LC. Before this PR AWS-LC only supported ML-DSA-65, as such, we were utilizing the
void *ptr
ofevp_pkey_st
, rather than a distinct structure for ML-DSA.This PR introduces the new structure
NISTDSA_KEY * nistdsa_key;
insideevp_pkey_st
to support ML-DSA and any additional FIPS digital signature algorithms provided by NIST, should AWS-LC wish to include them in the library.While the structure
DSA
already exists it does not provide support for FIPS-like signature APIs (see more at NIST api conventions. Rather than create a PKEY struct of the formMLDSA_KEY
that can only support ML-DSA, this is an opportunity to build support for future signature algorithms that have similar. calling structures, de-randomized testing modes, API converntions, etc. by making a more generic structure type -- much like we did forKEM_KEY
. Under the design in this PR, adding SLH-DSA to the PKEY struct would be very simple, as it conforms to aNISTDSA_KEY
in design. So too will be true of any additional signature algorithms produced by NISTs call for additional signature algorithms.As, such,
NISTDSA_KEY
utilizes a new structure to hold public/secret keys, as well as aNISTDSA
struct which defines signature algorithm specific information:This allows us to use a single PKEY structure for all NIST FIPS signature algorithms, much like the existing PKEY struct
KEM_KEY *kem_key
for KEMS. As a consequence, we are now able to define signature methods such as:much like the existing kem.c file.
These structures will be incredibly useful for subsequent PRs, in which we will be adding de-randomized APIs to support FIPS validation and KATs from seeds. In effect, we will be extending the method to include:
The directory
dilithium/p_dilithium3.c
is used to house genericPKEY
operations, as well as NISTDSA specific EVP functions such asEVP_PKEY_nistdsa_set_params
,EVP_PKEY_nistdsa_set_params
, which work in a similar way to p_kem.c functionsEVP_PKEY_CTX_kem_set_params
andEVP_PKEY_kem_set_params
.The directory
dilithium/p_dilithium3_asn1.c
is used to house genericasn.1
operations for NIST FIPS DSA algorithms.Rather than rename/relocate these files in this PR (which will convolute the CR), I will move these files in a subsequent PR.
2. Internal Design
We introduce new structures:
NISTDSA_METHOD
,NISTDSA
,NISTDSA_KEY
which are very similar to how both EC Crypto, and the KEM API is implemented. The figure above shows the newly proposed structures and their integration into the existing EVP structures.NISTDSA_METHOD
is a table of function pointers with 5 functions defined for aNISTDSA
: key generation, key generation internal (for testing/FIPS), sign, sign internal (for testing/FIPS), and verify. EveryNISTDSA
implementation has to implement this API, for examplesig_ml_dsa_44_method
implements the three functions for ML-DSA-44 (analogous toEC_METHOD
and for example,EC_GFp_nistz256_method
).NISTDSA
is a structure that holds basic information about the DSA: the id, size of parameters, and the pointer to the implementation of the correspondingNISTDSA_METHOD
.NISTDSA_KEY
structure is a helper structure that holds pointers to public and secret key and the pointer to the correspondingNISTDSA
.NISTDSA_PKEY_CTX
is a helper structure used to store DSA parameters in anEVP_PKEY_CTX
object (the same asEC_PKEY_CTX
). SinceNISTDSA
has everything we need, that’s what we store inNISTDSA_PKEY_CTX
.3. OID changes
We now have real OIDs available from https://csrc.nist.gov/projects/computer-security-objects-register/algorithm-registration. These have been added to the
obj
files and automatically populated bygo run objects.go
. We include the following NIDs for ML-DSA:and a "top-level" NID
EVP_PKEY_NISTDSA
(similar to EVP_PKEY_KEM to subset all NIST FIPS DSA algorithms. Much like for the KEM API, we include functionsSIG_find_dsa_by_nid(int nid)
to return actual algorithm specific methods.4. Testing structure changes
Prior to this PR all testing for ML-DSA-65 was done as a series of g-tests. As we now have the ability to get algorithm/security level specific parameters from the
NISTDSA
struct, I have overhauled the testing suite to be parameterized over the currently supported signature algorithms:For each of the above parameter sets we run:
5. X.509 changes
Changes to X.509 code have been minimized to only the required changes to support this PR. This is already a big PR and I want to avoid expansion wherever possible. For X.509 the changes predominantly are regarding the change of NIDs from the old Dilithium NIDs to the new NIST DSA NIDs/OIDs.
As the OIDs changed, so too much the test certificates
kDilithium3Cert
,kDilithium3CertNull
, andkDilithium3CertParam
. These have been regenerated using the following:6. Speed Tool
ML-DSA-44
andML-DSA-87
have been added to the speed tool. To facilitate the new APIs used in this PR, the API version has been incremented by 1. The speed tool now produces benchmarks for all three parameter levels, example output:Callouts:
dilithium/p_dilithium3.c
all dilithium3 pkey specific functionality is now genericdilithium/p_dilithium3_asn1.c
all dilithium3 asn1 specific functionality is now genericdilithium/p_dilithium_test.cc
all dilithium3 testing specific functionality is now genericdilithium/internal.h
is a new file, added to maintain consistency withfipsmodule/kem/internal.h
Testing:
See above for description of changes to testing framework.
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.