Rename Dilithium to canonical ML-DSA (FIPS 204) names

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.

Author: Frauschi

.wolfssl_known_macro_extras

@@ -652,7 +652,6 @@ WC_ASYNC_NO_SHA512
 WC_ASYNC_NO_X25519
 WC_ASYNC_THREAD_BIND
 WC_CACHE_RESISTANT_BASE64_TABLE
-WC_DILITHIUM_FIXED_ARRAY
 WC_DISABLE_RADIX_ZERO_PAD
 WC_FLAG_DONT_USE_AESNI
 WC_FORCE_LINUXKM_FORTIFY_SOURCE
@@ -737,12 +736,6 @@ WOLFSSL_CLANG_TIDY
 WOLFSSL_CLIENT_EXAMPLE
 WOLFSSL_CONTIKI
 WOLFSSL_CRL_ALLOW_MISSING_CDP
-WOLFSSL_DILITHIUM_ASSIGN_KEY
-WOLFSSL_DILITHIUM_NO_CHECK_KEY
-WOLFSSL_DILITHIUM_NO_MAKE
-WOLFSSL_DILITHIUM_REVERSE_HASH_OID
-WOLFSSL_DILITHIUM_SIGN_CHECK_W0
-WOLFSSL_DILITHIUM_SIGN_CHECK_Y
 WOLFSSL_DISABLE_EARLY_SANITY_CHECKS
 WOLFSSL_DRBG_SHA256
 WOLFSSL_DTLS_DISALLOW_FUTURE
@@ -831,6 +824,8 @@ WOLFSSL_NO_DECODE_EXTRA
 WOLFSSL_NO_DEL_HANDLE
 WOLFSSL_NO_DER_TO_PEM
 WOLFSSL_NO_DH186
+WOLFSSL_NO_DILITHIUM_LEGACY_GATES
+WOLFSSL_NO_DILITHIUM_LEGACY_NAMES
 WOLFSSL_NO_DTLS_SIZE_CHECK
 WOLFSSL_NO_ETM_ALERT
 WOLFSSL_NO_FENCE

CMakeLists.txt

@@ -673,21 +673,31 @@ if (WOLFSSL_PQC_HYBRIDS)
     list(APPEND WOLFSSL_DEFINITIONS "-DWOLFSSL_PQC_HYBRIDS")
 endif()
 
-# Dilithium
+# ML-DSA (FIPS 204)
+add_option(WOLFSSL_MLDSA
+    "Enable the wolfSSL PQ ML-DSA (FIPS 204) implementation (default: disabled)"
+    "no" "yes;no")
+# Legacy alias: WOLFSSL_DILITHIUM. Kept for backward compatibility.
 add_option(WOLFSSL_DILITHIUM
-    "Enable the wolfSSL PQ Dilithium (ML-DSA) implementation (default: disabled)"
+    "Legacy alias for WOLFSSL_MLDSA (default: disabled)"
     "no" "yes;no")
 
 if (WOLFSSL_DILITHIUM)
-    list(APPEND WOLFSSL_DEFINITIONS "-DHAVE_DILITHIUM")
+    message(DEPRECATION
+        "WOLFSSL_DILITHIUM is the legacy alias for WOLFSSL_MLDSA and will be "
+        "removed in a future release. Set -DWOLFSSL_MLDSA=yes instead.")
+endif()
+
+if (WOLFSSL_MLDSA OR WOLFSSL_DILITHIUM)
+    list(APPEND WOLFSSL_DEFINITIONS "-DWOLFSSL_HAVE_MLDSA")
     list(APPEND WOLFSSL_DEFINITIONS "-DWOLFSSL_SHA3")
     list(APPEND WOLFSSL_DEFINITIONS "-DWOLFSSL_SHAKE128")
     list(APPEND WOLFSSL_DEFINITIONS "-DWOLFSSL_SHAKE256")
 
-    set_wolfssl_definitions("HAVE_DILITHIUM"       RESULT)
-    set_wolfssl_definitions("WOLFSSL_SHA3"         RESULT)
-    set_wolfssl_definitions("WOLFSSL_SHAKE128"     RESULT)
-    set_wolfssl_definitions("WOLFSSL_SHAKE256"     RESULT)
+    set_wolfssl_definitions("WOLFSSL_HAVE_MLDSA" RESULT)
+    set_wolfssl_definitions("WOLFSSL_SHA3"       RESULT)
+    set_wolfssl_definitions("WOLFSSL_SHAKE128"   RESULT)
+    set_wolfssl_definitions("WOLFSSL_SHAKE256"   RESULT)
 endif()
 
 # LMS

ChangeLog.md

@@ -23,6 +23,19 @@
   NULL/length/`MISSING_KEY` checks as the `*Hash*` family.
   `wc_SlhDsaKey_VerifyMsg` is unchanged. All three gain doxygen coverage.
 
+* Renamed the post-quantum signature implementation from its
+  pre-standardization name *Dilithium* to its NIST-standardized name
+  **ML-DSA** (FIPS 204), mirroring the earlier Kyber → ML-KEM rename
+  in `wc_mlkem.{h,c}`. The legacy `<wolfssl/wolfcrypt/dilithium.h>`
+  header, `dilithium_key` type, `wc_dilithium_*` / `wc_Dilithium_*`
+  functions, and `HAVE_DILITHIUM` / `WOLFSSL_DILITHIUM_*` /
+  `WC_DILITHIUM_*` build gates remain available through a temporary
+  compatibility shim, so application code keeps compiling unchanged.
+  See [doc/dilithium-to-mldsa-migration.md](doc/dilithium-to-mldsa-migration.md)
+  for the full list of renamed symbols, the new `WOLFSSL_MLDSA` cmake
+  option / `--enable-mldsa` configure switch, and the migration steps
+  for moving consumer code to the canonical API.
+
 * TLS 1.3: zero traffic key staging buffers in `SetKeysSide()` once a
   CryptoCB callback has imported the AES key into a Secure Element
   (`aes->devCtx != NULL`).  Clears `keys->{client,server}_write_key`

IDE/INTIME-RTOS/libwolfssl.vcxproj

@@ -42,7 +42,7 @@
 	<ClCompile Include="..\..\wolfcrypt\src\cpuid.c" />
 	<ClCompile Include="..\..\wolfcrypt\src\cryptocb.c" />
     <ClCompile Include="..\..\wolfcrypt\src\des3.c" />
-	<ClCompile Include="..\..\wolfcrypt\src\dilithium.c" />
+	<ClCompile Include="..\..\wolfcrypt\src\wc_mldsa.c" />
     <ClCompile Include="..\..\wolfcrypt\src\dh.c" />
     <ClCompile Include="..\..\wolfcrypt\src\dsa.c" />
     <ClCompile Include="..\..\wolfcrypt\src\ecc.c" />

IDE/INTIME-RTOS/wolfssl-lib.vcxproj

@@ -79,7 +79,7 @@
     <ClCompile Include="..\..\wolfcrypt\src\cpuid.c" />
     <ClCompile Include="..\..\wolfcrypt\src\cryptocb.c" />
     <ClCompile Include="..\..\wolfcrypt\src\curve448.c" />
-    <ClCompile Include="..\..\wolfcrypt\src\dilithium.c" />
+    <ClCompile Include="..\..\wolfcrypt\src\wc_mldsa.c" />
     <ClCompile Include="..\..\wolfcrypt\src\eccsi.c" />
     <ClCompile Include="..\..\wolfcrypt\src\ed448.c" />
     <ClCompile Include="..\..\wolfcrypt\src\evp.c">

IDE/WIN10/wolfssl-fips.vcxproj

@@ -318,7 +318,7 @@
     <ClCompile Include="..\..\wolfcrypt\src\wolfmath.c" />
     <ClCompile Include="..\..\wolfcrypt\src\wolfevent.c" />
     <ClCompile Include="..\..\wolfcrypt\src\pkcs12.c" />
-    <ClCompile Include="..\..\wolfcrypt\src\dilithium.c" />
+    <ClCompile Include="..\..\wolfcrypt\src\wc_mldsa.c" />
     <ClCompile Include="..\..\wolfcrypt\src\wc_lms.c" />
     <ClCompile Include="..\..\wolfcrypt\src\wc_lms_impl.c" />
     <ClCompile Include="..\..\wolfcrypt\src\wc_xmss.c" />

IDE/XCODE/wolfssl-FIPS.xcodeproj/project.pbxproj

@@ -122,6 +122,7 @@
 		700F0CF22A2FC11300755BA7 /* curve448.h in CopyFiles */ = {isa = PBXBuildFile; fileRef = 700F0CD32A2FC0D500755BA7 /* curve448.h */; };
 		700F0CF32A2FC11300755BA7 /* curve25519.h in CopyFiles */ = {isa = PBXBuildFile; fileRef = 700F0CC82A2FC0D500755BA7 /* curve25519.h */; };
 		700F0CF42A2FC11300755BA7 /* dilithium.h in CopyFiles */ = {isa = PBXBuildFile; fileRef = 700F0CE52A2FC0D500755BA7 /* dilithium.h */; };
+		700F0CE52A2FC0D500755BC0 /* wc_mldsa.h in CopyFiles */ = {isa = PBXBuildFile; fileRef = 700F0CE52A2FC0D500755BC1 /* wc_mldsa.h */; };
 		700F0CF52A2FC11300755BA7 /* eccsi.h in CopyFiles */ = {isa = PBXBuildFile; fileRef = 700F0CDB2A2FC0D500755BA7 /* eccsi.h */; };
 		700F0CF62A2FC11300755BA7 /* ed448.h in CopyFiles */ = {isa = PBXBuildFile; fileRef = 700F0CD22A2FC0D500755BA7 /* ed448.h */; };
 		700F0CF72A2FC11300755BA7 /* ed25519.h in CopyFiles */ = {isa = PBXBuildFile; fileRef = 700F0CE12A2FC0D500755BA7 /* ed25519.h */; };
@@ -280,6 +281,7 @@
 				700F0CF22A2FC11300755BA7 /* curve448.h in CopyFiles */,
 				700F0CF32A2FC11300755BA7 /* curve25519.h in CopyFiles */,
 				700F0CF42A2FC11300755BA7 /* dilithium.h in CopyFiles */,
+				700F0CE52A2FC0D500755BC0 /* wc_mldsa.h in CopyFiles */,
 				700F0CF52A2FC11300755BA7 /* eccsi.h in CopyFiles */,
 				700F0CF62A2FC11300755BA7 /* ed448.h in CopyFiles */,
 				700F0CF72A2FC11300755BA7 /* ed25519.h in CopyFiles */,
@@ -583,6 +585,7 @@
 		700F0CE22A2FC0D500755BA7 /* ge_448.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; name = ge_448.h; path = ../../wolfssl/wolfcrypt/ge_448.h; sourceTree = "<group>"; };
 		700F0CE42A2FC0D500755BA7 /* pkcs12.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; name = pkcs12.h; path = ../../wolfssl/wolfcrypt/pkcs12.h; sourceTree = "<group>"; };
 		700F0CE52A2FC0D500755BA7 /* dilithium.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; name = dilithium.h; path = ../../wolfssl/wolfcrypt/dilithium.h; sourceTree = "<group>"; };
+		700F0CE52A2FC0D500755BC1 /* wc_mldsa.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; name = wc_mldsa.h; path = ../../wolfssl/wolfcrypt/wc_mldsa.h; sourceTree = "<group>"; };
 		700F0CE62A2FC0D500755BA7 /* sakke.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; name = sakke.h; path = ../../wolfssl/wolfcrypt/sakke.h; sourceTree = "<group>"; };
 		700F0CE72A2FC0D500755BA7 /* signature.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; name = signature.h; path = ../../wolfssl/wolfcrypt/signature.h; sourceTree = "<group>"; };
 		700F0CE82A2FC0D500755BA7 /* wc_pkcs11.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; name = wc_pkcs11.h; path = ../../wolfssl/wolfcrypt/wc_pkcs11.h; sourceTree = "<group>"; };
@@ -634,6 +637,7 @@
 				700F0CD32A2FC0D500755BA7 /* curve448.h */,
 				700F0CC82A2FC0D500755BA7 /* curve25519.h */,
 				700F0CE52A2FC0D500755BA7 /* dilithium.h */,
+				700F0CE52A2FC0D500755BC1 /* wc_mldsa.h */,
 				700F0CDB2A2FC0D500755BA7 /* eccsi.h */,
 				700F0CD22A2FC0D500755BA7 /* ed448.h */,
 				700F0CE12A2FC0D500755BA7 /* ed25519.h */,

IDE/XCODE/wolfssl.xcodeproj/project.pbxproj

@@ -253,6 +253,7 @@
 		700F0C0A2A2FBC5100755BA7 /* curve448.h in CopyFiles */ = {isa = PBXBuildFile; fileRef = 700F0BE32A2FBC1500755BA7 /* curve448.h */; };
 		700F0C0B2A2FBC5100755BA7 /* curve25519.h in CopyFiles */ = {isa = PBXBuildFile; fileRef = 700F0BE52A2FBC1500755BA7 /* curve25519.h */; };
 		700F0C0C2A2FBC5100755BA7 /* dilithium.h in CopyFiles */ = {isa = PBXBuildFile; fileRef = 700F0BEF2A2FBC1500755BA7 /* dilithium.h */; };
+		700F0BEF2A2FBC1500755BC0 /* wc_mldsa.h in CopyFiles */ = {isa = PBXBuildFile; fileRef = 700F0BEF2A2FBC1500755BC1 /* wc_mldsa.h */; };
 		700F0C0D2A2FBC5100755BA7 /* eccsi.h in CopyFiles */ = {isa = PBXBuildFile; fileRef = 700F0BF72A2FBC1600755BA7 /* eccsi.h */; };
 		700F0C0E2A2FBC5100755BA7 /* ed448.h in CopyFiles */ = {isa = PBXBuildFile; fileRef = 700F0BF82A2FBC1600755BA7 /* ed448.h */; };
 		700F0C0F2A2FBC5100755BA7 /* ed25519.h in CopyFiles */ = {isa = PBXBuildFile; fileRef = 700F0BF42A2FBC1600755BA7 /* ed25519.h */; };
@@ -617,6 +618,7 @@
 				700F0C0A2A2FBC5100755BA7 /* curve448.h in CopyFiles */,
 				700F0C0B2A2FBC5100755BA7 /* curve25519.h in CopyFiles */,
 				700F0C0C2A2FBC5100755BA7 /* dilithium.h in CopyFiles */,
+				700F0BEF2A2FBC1500755BC0 /* wc_mldsa.h in CopyFiles */,
 				700F0C0D2A2FBC5100755BA7 /* eccsi.h in CopyFiles */,
 				700F0C0E2A2FBC5100755BA7 /* ed448.h in CopyFiles */,
 				700F0C0F2A2FBC5100755BA7 /* ed25519.h in CopyFiles */,
@@ -983,6 +985,7 @@
 		700F0BED2A2FBC1500755BA7 /* chacha20_poly1305.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; name = chacha20_poly1305.h; path = ../../wolfssl/wolfcrypt/chacha20_poly1305.h; sourceTree = "<group>"; };
 		700F0BEE2A2FBC1500755BA7 /* cryptocb.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; name = cryptocb.h; path = ../../wolfssl/wolfcrypt/cryptocb.h; sourceTree = "<group>"; };
 		700F0BEF2A2FBC1500755BA7 /* dilithium.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; name = dilithium.h; path = ../../wolfssl/wolfcrypt/dilithium.h; sourceTree = "<group>"; };
+		700F0BEF2A2FBC1500755BC1 /* wc_mldsa.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; name = wc_mldsa.h; path = ../../wolfssl/wolfcrypt/wc_mldsa.h; sourceTree = "<group>"; };
 		700F0BF02A2FBC1500755BA7 /* sakke.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; name = sakke.h; path = ../../wolfssl/wolfcrypt/sakke.h; sourceTree = "<group>"; };
 		700F0BF12A2FBC1600755BA7 /* cpuid.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; name = cpuid.h; path = ../../wolfssl/wolfcrypt/cpuid.h; sourceTree = "<group>"; };
 		700F0BF22A2FBC1600755BA7 /* selftest.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; name = selftest.h; path = ../../wolfssl/wolfcrypt/selftest.h; sourceTree = "<group>"; };
@@ -1144,6 +1147,7 @@
 				700F0BE32A2FBC1500755BA7 /* curve448.h */,
 				700F0BE52A2FBC1500755BA7 /* curve25519.h */,
 				700F0BEF2A2FBC1500755BA7 /* dilithium.h */,
+				700F0BEF2A2FBC1500755BC1 /* wc_mldsa.h */,
 				700F0BF72A2FBC1600755BA7 /* eccsi.h */,
 				700F0BF82A2FBC1600755BA7 /* ed448.h */,
 				700F0BF42A2FBC1600755BA7 /* ed25519.h */,

cmake/functions.cmake

@@ -210,8 +210,8 @@ function(generate_build_flags)
     if(WOLFSSL_MLKEM OR WOLFSSL_USER_SETTINGS)
         set(BUILD_WC_MLKEM "yes" PARENT_SCOPE)
     endif()
-    if(WOLFSSL_DILITHIUM OR WOLFSSL_USER_SETTINGS)
-        set(BUILD_DILITHIUM "yes" PARENT_SCOPE)
+    if(WOLFSSL_MLDSA OR WOLFSSL_DILITHIUM OR WOLFSSL_USER_SETTINGS)
+        set(BUILD_MLDSA "yes" PARENT_SCOPE)
     endif()
     if(WOLFSSL_FALCON OR WOLFSSL_USER_SETTINGS)
         set(BUILD_FALCON "yes" PARENT_SCOPE)
@@ -1029,8 +1029,8 @@ function(generate_lib_src_list LIB_SOURCES)
             list(APPEND LIB_SOURCES wolfcrypt/src/falcon.c)
         endif()
 
-        if(BUILD_DILITHIUM)
-            list(APPEND LIB_SOURCES wolfcrypt/src/dilithium.c)
+        if(BUILD_MLDSA)
+            list(APPEND LIB_SOURCES wolfcrypt/src/wc_mldsa.c)
 
             if(BUILD_INTELASM)
                 list(APPEND LIB_SOURCES wolfcrypt/src/wc_mldsa_asm.S)

cmake/options.h.in

@@ -96,8 +96,8 @@ extern "C" {
 #cmakedefine HAVE_CURVE448
 #undef HAVE_DH_DEFAULT_PARAMS
 #cmakedefine HAVE_DH_DEFAULT_PARAMS
-#undef HAVE_DILITHIUM
-#cmakedefine HAVE_DILITHIUM
+#undef WOLFSSL_HAVE_MLDSA
+#cmakedefine WOLFSSL_HAVE_MLDSA
 #undef HAVE_ECC
 #cmakedefine HAVE_ECC
 #undef HAVE_ECH