NIST standardized the pre-standardization Dilithium signature scheme as
ML-DSA in FIPS 204. Migrate the provider's user-visible surface to
canonical spellings, with a temporary shim that preserves source-level
backward compatibility for existing consumers.
Renames
-------
* File: wolfcrypt/src/dilithium.c -> wolfcrypt/src/wc_mldsa.c
* New canonical header: wolfssl/wolfcrypt/wc_mldsa.h
* Types: dilithium_key -> MlDsaKey, wc_dilithium_params -> MlDsaParams
* Functions: wc_dilithium_* / wc_Dilithium_* -> wc_MlDsaKey_*
* Build gates: HAVE_DILITHIUM -> WOLFSSL_HAVE_MLDSA,
WOLFSSL_DILITHIUM_* / WC_DILITHIUM_* -> WOLFSSL_MLDSA_* / WC_MLDSA_*
* Configure flag: --enable-mldsa (legacy --enable-dilithium still works)
* CMake option: WOLFSSL_MLDSA (legacy WOLFSSL_DILITHIUM emits a
DEPRECATION message)
Backward compatibility
----------------------
wolfssl/wolfcrypt/dilithium.h is now a temporary compatibility shim:
* Forward-translates legacy build gates to canonical (the two sub-gates
read by certs_test.h are translated in settings.h so the auto-generated
header is reachable without including dilithium.h; the remainder lives
in dilithium.h itself).
* Reverse-translates canonical gates back to legacy so unmigrated
consumer code keying off HAVE_DILITHIUM / WOLFSSL_DILITHIUM_* keeps
compiling.
* Provides macro / static-inline aliases for the legacy type and
function names so source-level callers compile unchanged. Sets
WC_DILITHIUMKEY_TYPE_DEFINED to suppress strict-C99 typedef
redefinition in asn_public.h.
Two opt-outs are honored: WOLFSSL_NO_DILITHIUM_LEGACY_GATES disables
build-gate translation; WOLFSSL_NO_DILITHIUM_LEGACY_NAMES disables the
symbol aliases. Both are temporary and the shim will be removed in a
future release. doc/dilithium-to-mldsa-migration.md describes the
migration path for downstream consumers.
ABI note
--------
The library now exports wc_MlDsaKey_* instead of wc_dilithium_*.
Pre-built binaries that linked against the legacy symbols need to
recompile against the shim header (which resolves to the new symbols at
compile time) or migrate to the canonical names directly. Source code
keeps building unchanged.
Other changes
-------------
* wolfssl/wolfcrypt/memory.h: drop ML-DSA sub-gate branching for static
memory pool sizing; WOLFSSL_HAVE_MLDSA builds now pick the larger
LARGEST_MEM_BUCKET / WOLFMEM_BUCKETS / WOLFMEM_DIST unconditionally.
Override these macros for small-mem builds.
* gencertbuf.pl + wolfssl/certs_test.h: outer guards migrated to the
canonical WOLFSSL_HAVE_MLDSA spelling.
* tests/api/test_mldsa.c: adds compile-time API surface validators
(canonical wc_MlDsaKey_* surface plus legacy alias surface) so
signature drift produces a build error during make check.
* IDE files (Xcode, INTIME-RTOS, WIN10, VS2022, CSharp wrapper), Zephyr
CMakeLists.txt, and autotools include.am updated for the rename.
* DYNAMIC_TYPE_DILITHIUM and ML_DSA_PCT_E retained as internal symbols;
scheduled to be renamed alongside the eventual shim removal.
Follow up to PR #10450 with some minor fixes:
* FIPS 205 numbering: slh_sign is §10.2.1 Alg 22; slh_verify is Alg 24;
hash_slh_verify is Alg 25 (impl comments and doxygen).
* Widen wc_SlhDsaKey_SignHashWithRandom's addRnd to const byte* to
match wc_SlhDsaKey_SignWithRandom.
* Make the SLHDSA_PHMSG_MAX_LEN invariant explicit with a named
SLHDSA_LARGEST_APPROVED_PHM_LEN constant and a wc_static_assert.
* SHAKE128/SHAKE256 round-trip and length-rejection coverage for both
SignHash and VerifyHash.
* Doxygen: briefs for the five DER encode/decode APIs; accurate
decoder failure-rollback wording; tighter return-code lists for
Verify and VerifyMsg.
* ChangeLog: silent-failure caveat for raw messages whose length
happens to equal the digest size of the chosen hashType.
wc_SlhDsaKey_{Sign,Verify}Hash* previously accepted the raw message and
performed the pre-hash internally. They now require the caller to hash the
message first and pass the resulting digest -- the functions no longer call
wc_*Hash() themselves and feed the supplied digest directly into the M'
construction. Parameters are renamed from msg/msgSz to hash/hashSz to reflect
this, and hashSz is validated against wc_HashGetDigestSize(hashType) per
FIPS 205 Section 10.2.2 (32 for SHAKE128, 64 for SHAKE256), returning
BAD_LENGTH_E on mismatch.
This matches ML-DSA's wc_dilithium_{sign,verify}_ctx_hash, NIST ACVP
signatureInterface=external / preHash=preHash vectors, and other libraries
(OpenSSL HASH-ML-DSA, leancrypto, mldsa-native). It also enables distributed
signers and HSM-style flows where the digest is computed separately from the
signing operation.
Migration: callers must now hash the message before invoking these APIs;
passing the raw message will either fail length validation or produce
signatures over the wrong input. The M'-supplied wc_SlhDsaKey_SignMsg* /
VerifyMsg family (FIPS 205 internal interface, Algorithms 19/20) is
unchanged but gains stricter input validation and doxygen coverage.
When WOLF_CRYPTO_CB_AES_SETKEY is enabled and a CryptoCB callback
imports the AES key into a Secure Element (aes->devCtx != NULL), the
TLS-layer copy in keys->{client,server}_write_key has no further
consumer: the software key schedule is not populated on offload.
ForceZero it in SetKeysSide() per provisioned side.
The static IVs (keys->{client,server}_write_IV and
keys->aead_{enc,dec}_imp_IV) are left intact because BuildTls13Nonce()
reads aead_{enc,dec}_imp_IV on every record (RFC 8446 Section 5.3).
Scope: TLS 1.3, non-DTLS, non-QUIC. DTLS 1.3 needs the write keys
in Dtls13EpochCopyKeys; TLS 1.2 needs them for rehandshake; QUIC is
untouched pending audit.
Add two memio tests (test_wc_CryptoCb_Tls13_Key_{Zero_After_Offload,
No_Zero_Without_Offload}) that pin AES-GCM and check key / IV state
after the handshake and a KeyUpdate round.
Signed-off-by: Sameeh Jubran <sameeh@wolfssl.com>
Tobias Frauenschläger
Sameeh Jubran
JacobBarthelmeh
Eric Blankenhorn
Joshua Okeleke
Daniel Pouzzner
Lealem Amedie
Chris Conlon
Dimitri Papadopoulos
John Safranek
Anthony Hu