[PATCH v7 0/8] lib/crypto: Add ML-DSA signing

David Howells
2025-11-06T17:45:10Z

Hi Herbert, Eric, et al.,

Building on the SHA-3 lib-crypto patches now in Eric's tree, here's a set of
patches does the following:

(1) Add SHAKE-256 crypto_sig support, generating 32-byte fixed output. The
XOF features aren't available through this. SHAKE-128 crypto_sig support
isn't required for ML-DSA, so I haven't implemented that at this time.

(2) Add ML-DSA signature verification code, extracted from Stephan Mueller's
Leancrypto project. It is accessed through crypto_sig.

(3) Add a kunit test in three installments (due to size) to add some
testing for the three different levels of ML-DSA (44, 65 and 87).

(4) Modify PKCS#7 support to allow kernel module signatures to carry
authenticatedAttributes as OpenSSL refuses to let them be opted out of
for ML-DSA (CMS_NOATTR). This adds an extra digest calculation to the
process.

(5) Modify PKCS#7 to pass the authenticatedAttributes directly to the
ML-DSA algorithm rather than passing over a digest as is done with RSA
as ML-DSA wants to do its own hashing and will add other stuff into
the hash. We could use hashML-DSA or an external mu instead, but they
aren't standardised for CMS yet.

(6) Add support to the PKCS#7 and X.509 parsers for ML-DSA.

(7) Modify sign-file to handle OpenSSL not permitting CMS_NOATTR with
ML-DSA.

(8) Allow SHA-3 algorithms, including SHAKE256, to be used for the message
digest and add ML-DSA to the choice of algorithm with which to sign.

With that, ML-DSA signing appears to work.

This is based on Eric's libcrypto-next branch.

The patches can also be found here:

https://git.kernel.org/pub/scm/linux/kernel/git/dhowells/linux-fs.git/log/?h=keys-pqc

David

Changes
=======
ver #7)
- Rebased on Eric's tree as that now contains all the necessary SHA-3
infrastructure and drop the SHA-3 patches from here.
- Added a minimal patch to provide shake256 support for crypto_sig.
- Got rid of the memory allocation wrappers.
- Removed the ML-DSA keypair generation code and the signing code, leaving
only the signature verification code.
- Removed the secret key handling code.
- Removed the secret keys from the kunit tests and the signing testing.
- Removed some unused bits from the ML-DSA code.
- Downgraded the kdoc comments to ordinary comments, but keep the markup
for easier comparison to Leancrypto.

ver #6)
- Added a patch to make the jitterentropy RNG use lib/sha3.
- Added back the crypto/sha3_generic changes.
- Added ML-DSA implementation (still needs more cleanup).
- Added kunit test for ML-DSA.
- Modified PKCS#7 to accommodate ML-DSA.
- Modified PKCS#7 and X.509 to allow ML-DSA to be specified and used.
- Modified sign-file to not use CMS_NOATTR with ML-DSA.
- Allowed SHA3 and SHAKE* algorithms for module signing default.
- Allowed ML-DSA-{44,65,87} to be selected as the module signing default.

ver #5)
- Fix gen-hash-testvecs.py to correctly handle algo names that contain a
dash.
- Fix gen-hash-testvecs.py to not generate HMAC for SHA3-* or SHAKE* as
these don't currently have HMAC variants implemented.
- Fix algo names to be correct.
- Fix kunit module description as it now tests all SHA3 variants.

ver #4)
- Fix a couple of arm64 build problems.
- Doc fixes:
- Fix the description of the algorithm to be closer to the NIST spec's
terminology.
- Don't talk of finialising the context for XOFs.
- Don't say "Return: None".
- Declare the "Context" to be "Any context" and make no mention of the
fact that it might use the FPU.
- Change "initialise" to "initialize".
- Don't warn that the context is relatively large for stack use.
- Use size_t for size parameters/variables.
- Make the module_exit unconditional.
- Dropped the crypto/ dir-affecting patches for the moment.

ver #3)
- Renamed conflicting arm64 functions.
- Made a separate wrapper API for each algorithm in the family.
- Removed sha3_init(), sha3_reinit() and sha3_final().
- Removed sha3_ctx::digest_size.
- Renamed sha3_ctx::partial to sha3_ctx::absorb_offset.
- Refer to the output of SHAKE* as "output" not "digest".
- Moved the Iota transform into the one-round function.
- Made sha3_update() warn if called after sha3_squeeze().
- Simplified the module-load test to not do update after squeeze.
- Added Return: and Context: kdoc statements and expanded the kdoc
headers.
- Added an API description document.
- Overhauled the kunit tests.
- Only have one kunit test.
- Only call the general hash tester on one algo.
- Add separate simple cursory checks for the other algos.
- Add resqueezing tests.
- Add some NIST example tests.
- Changed crypto/sha3_generic to use this
- Added SHAKE128/256 to crypto/sha3_generic and crypto/testmgr
- Folded struct sha3_state into struct sha3_ctx.

ver #2)
- Simplify the endianness handling.
- Rename sha3_final() to sha3_squeeze() and don't clear the context at the
end as it's permitted to continue calling sha3_final() to extract
continuations of the digest (needed by ML-DSA).
- Don't reapply the end marker to the hash state in continuation
sha3_squeeze() unless sha3_update() gets called again (needed by
ML-DSA).
- Give sha3_squeeze() the amount of digest to produce as a parameter
rather than using ctx->digest_size and don't return the amount digested.
- Reimplement sha3_final() as a wrapper around sha3_squeeze() that
extracts ctx->digest_size amount of digest and then zeroes out the
context. The latter is necessary to avoid upsetting
hash-test-template.h.
- Provide a sha3_reinit() function to clear the state, but to leave the
parameters that indicate the hash properties unaffected, allowing for
reuse.
- Provide a sha3_set_digestsize() function to change the size of the
digest to be extracted by sha3_final(). sha3_squeeze() takes a
parameter for this instead.
- Don't pass the digest size as a parameter to shake128/256_init() but
rather default to 128/256 bits as per the function name.
- Provide a sha3_clear() function to zero out the context.

David Howells (8):
crypto: Add support for shake256 through crypto_shash
crypto: Add ML-DSA/Dilithium verify support
crypto: Add ML-DSA-44 pure rejection test vectors as a kunit test
crypto: Add ML-DSA-65 pure rejection test vectors as a kunit test
crypto: Add ML-DSA-87 pure rejection test vectors as a kunit test
pkcs7: Allow the signing algo to calculate the digest itself
pkcs7, x509: Add ML-DSA support
modsign: Enable ML-DSA module signing

Documentation/admin-guide/module-signing.rst | 15 +-
certs/Kconfig | 24 +
certs/Makefile | 3 +
crypto/Kconfig | 1 +
crypto/Makefile | 1 +
crypto/asymmetric_keys/pkcs7_parser.c | 19 +-
crypto/asymmetric_keys/pkcs7_verify.c | 52 +-
crypto/asymmetric_keys/public_key.c | 7 +
crypto/asymmetric_keys/x509_cert_parser.c | 24 +
crypto/ml_dsa/Kconfig | 32 +
crypto/ml_dsa/Makefile | 20 +
crypto/ml_dsa/dilithium.h | 547 ++
crypto/ml_dsa/dilithium_44.c | 33 +
crypto/ml_dsa/dilithium_44.h | 282 +
crypto/ml_dsa/dilithium_65.c | 33 +
crypto/ml_dsa/dilithium_65.h | 282 +
crypto/ml_dsa/dilithium_87.c | 33 +
crypto/ml_dsa/dilithium_87.h | 282 +
crypto/ml_dsa/dilithium_api.c | 429 ++
crypto/ml_dsa/dilithium_debug.h | 49 +
crypto/ml_dsa/dilithium_ntt.c | 89 +
crypto/ml_dsa/dilithium_ntt.h | 35 +
crypto/ml_dsa/dilithium_pack.h | 119 +
crypto/ml_dsa/dilithium_poly.c | 377 +
crypto/ml_dsa/dilithium_poly.h | 181 +
crypto/ml_dsa/dilithium_poly_c.h | 141 +
crypto/ml_dsa/dilithium_poly_common.h | 35 +
crypto/ml_dsa/dilithium_polyvec.h | 343 +
crypto/ml_dsa/dilithium_polyvec_c.h | 81 +
.../dilithium_pure_rejection_vectors_44.h | 489 ++
.../dilithium_pure_rejection_vectors_65.h | 4741 ++++++++++++
.../dilithium_pure_rejection_vectors_87.h | 6456 +++++++++++++++++
crypto/ml_dsa/dilithium_reduce.h | 85 +
crypto/ml_dsa/dilithium_rounding.c | 128 +
crypto/ml_dsa/dilithium_selftest.c | 142 +
crypto/ml_dsa/dilithium_service_helpers.h | 99 +
crypto/ml_dsa/dilithium_sig.c | 334 +
crypto/ml_dsa/dilithium_signature_c.c | 102 +
crypto/ml_dsa/dilithium_signature_c.h | 37 +
crypto/ml_dsa/dilithium_signature_helper.c | 97 +
crypto/ml_dsa/dilithium_signature_impl.h | 370 +
crypto/ml_dsa/dilithium_type.h | 102 +
crypto/ml_dsa/dilithium_zetas.c | 67 +
crypto/ml_dsa/signature_domain_separation.c | 203 +
crypto/ml_dsa/signature_domain_separation.h | 30 +
crypto/sha3.c | 42 +
include/crypto/public_key.h | 1 +
include/linux/oid_registry.h | 5 +
kernel/module/Kconfig | 5 +
scripts/sign-file.c | 26 +-
50 files changed, 17094 insertions(+), 36 deletions(-)
create mode 100644 crypto/ml_dsa/Kconfig
create mode 100644 crypto/ml_dsa/Makefile
create mode 100644 crypto/ml_dsa/dilithium.h
create mode 100644 crypto/ml_dsa/dilithium_44.c
create mode 100644 crypto/ml_dsa/dilithium_44.h
create mode 100644 crypto/ml_dsa/dilithium_65.c
create mode 100644 crypto/ml_dsa/dilithium_65.h
create mode 100644 crypto/ml_dsa/dilithium_87.c
create mode 100644 crypto/ml_dsa/dilithium_87.h
create mode 100644 crypto/ml_dsa/dilithium_api.c
create mode 100644 crypto/ml_dsa/dilithium_debug.h
create mode 100644 crypto/ml_dsa/dilithium_ntt.c
create mode 100644 crypto/ml_dsa/dilithium_ntt.h
create mode 100644 crypto/ml_dsa/dilithium_pack.h
create mode 100644 crypto/ml_dsa/dilithium_poly.c
create mode 100644 crypto/ml_dsa/dilithium_poly.h
create mode 100644 crypto/ml_dsa/dilithium_poly_c.h
create mode 100644 crypto/ml_dsa/dilithium_poly_common.h
create mode 100644 crypto/ml_dsa/dilithium_polyvec.h
create mode 100644 crypto/ml_dsa/dilithium_polyvec_c.h
create mode 100644 crypto/ml_dsa/dilithium_pure_rejection_vectors_44.h
create mode 100644 crypto/ml_dsa/dilithium_pure_rejection_vectors_65.h
create mode 100644 crypto/ml_dsa/dilithium_pure_rejection_vectors_87.h
create mode 100644 crypto/ml_dsa/dilithium_reduce.h
create mode 100644 crypto/ml_dsa/dilithium_rounding.c
create mode 100644 crypto/ml_dsa/dilithium_selftest.c
create mode 100644 crypto/ml_dsa/dilithium_service_helpers.h
create mode 100644 crypto/ml_dsa/dilithium_sig.c
create mode 100644 crypto/ml_dsa/dilithium_signature_c.c
create mode 100644 crypto/ml_dsa/dilithium_signature_c.h
create mode 100644 crypto/ml_dsa/dilithium_signature_helper.c
create mode 100644 crypto/ml_dsa/dilithium_signature_impl.h
create mode 100644 crypto/ml_dsa/dilithium_type.h
create mode 100644 crypto/ml_dsa/dilithium_zetas.c
create mode 100644 crypto/ml_dsa/signature_domain_separation.c
create mode 100644 crypto/ml_dsa/signature_domain_separation.h