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.
Modes (CTR, GCM, CCM, etc.) can be supported either directly or fallback
to invoking the crypto callback with a "direct" (ECB) mode.
Software implementation and AES tables are stripped under CB_ONLY_AES.
wc_swdev gains AES support so WOLF_CRYPTO_CB_ONLY_AES builds can be
tested.
crypto find cb support added to wc_AesSetKey in order to support current
CI tests that use INVALID_DEVID.
Add WOLF_CRYPTO_CB_ONLY_SHA256: when set, the SHA-256 software.
wc_Sha256FinalRaw is reduced to a stub returning NO_VALID_DEVID, and
sha256.h force-defines WOLFSSL_NO_HASH_RAW so the constant-time TLS HMAC
path falls back to its backend-opaque variant.
Incompatible with
WOLFSSL_SHA224, which aliases the SHA-256 statics; #error guard added.
Add wc_swdev support for SHA-256 for testing.
Extend the swdev callback to handle ECC operations: keygen, ECDH, sign,
verify, get-size, get-sig-size.
Relax WOLF_CRYPTO_CB_ONLY_ECC guards in the test suite so that tests run
under swdev, and wire wc_SwDev_Init/Cleanup into testsuite, client, and
server. Two tests are intentionally kept excluded even with swdev because
they call raw ECC math primitives (wc_ecc_mulmod, on-curve validation in
wc_ecc_import_x963) that are stripped below the cryptocb dispatch layer:
- ecc_mulmod_test (wolfcrypt/test/test.c)
- test_wc_ecc_import_x963_off_curve (tests/api/test_ecc.c)
Add a software crypto-callback device (wc_swdev) that lets the wolfcrypt
test suite run under WOLF_CRYPTO_CB_ONLY_* flags without per-test devId
plumbing. The bundle is a separately-compiled second copy of wolfcrypt
(software implementations enabled, WOLF_CRYPTO_CB_ONLY_* stripped) linked
into testwolfcrypt as a single relocatable object; every symbol is demoted
to local via objcopy --keep-global-symbol except wc_SwDev_Callback, so there
is no collision with the main libwolfssl.
A find callback routes unbound operations (devId == INVALID_DEVID) to the
swdev while letting real device IDs pass through.
wc_SwDev_Init / wc_SwDev_Cleanup hooks are wired into wolfcrypt/test/test.c.
cryptocb_test's WOLF_CRYPTO_CB_FIND and WOLF_CRYPTO_CB_ONLY_RSA blocks are
gated off under WOLFSSL_SWDEV.
Enable via --enable-swdev (requires --enable-cryptocb).
David Garske
Tobias Frauenschläger
Ruby Martin
Kareem
Daniel Pouzzner
Sean Parkinson
Paul Adelsbach
JacobBarthelmeh
Jeremiah Mackey
JeremiahM37
rizlik