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.
2026-07-05 03:30:49 +02:00 · 2026-05-08 15:02:12 +02:00
parent 460a87119e
commit fb6b62dd8e
31 changed files with 3549 additions and 2512 deletions
@@ -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
@@ -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
@@ -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`
@@ -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" />
@@ -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">
@@ -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" />
@@ -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 */,
@@ -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 */,
@@ -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)
@@ -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
@@ -1810,54 +1810,54 @@ AC_ARG_ENABLE([extra-pqc-hybrids],
 #  - SHA3, Shake128 and Shake256
 AC_ARG_ENABLE([mldsa],
    [AS_HELP_STRING([--enable-mldsa],[Enable ML-DSA/Dilithium (default: disabled)])],
-    [ ENABLED_DILITHIUM=$enableval ],
-    [ ENABLED_DILITHIUM=no ]
+    [ ENABLED_MLDSA=$enableval ],
+    [ ENABLED_MLDSA=no ]
    )
 # note, inherits default from "mldsa" clause above.
 AC_ARG_ENABLE([dilithium],
    [AS_HELP_STRING([--enable-dilithium],[Alias for --enable-mldsa])],
-    [ ENABLED_DILITHIUM=$enableval ]
+    [ ENABLED_MLDSA=$enableval ]
    )

-ENABLED_DILITHIUM_OPTS=$ENABLED_DILITHIUM
-ENABLED_DILITHIUM_MAKE_KEY=no
-ENABLED_DILITHIUM_SIGN=no
-ENABLED_DILITHIUM_VERIFY=no
-for v in `echo $ENABLED_DILITHIUM_OPTS | tr "," " "`
+ENABLED_MLDSA_OPTS=$ENABLED_MLDSA
+ENABLED_MLDSA_MAKE_KEY=no
+ENABLED_MLDSA_SIGN=no
+ENABLED_MLDSA_VERIFY=no
+for v in `echo $ENABLED_MLDSA_OPTS | tr "," " "`
 do
  case $v in
  yes)
    ENABLED_MLDSA44=yes
    ENABLED_MLDSA65=yes
    ENABLED_MLDSA87=yes
-    ENABLED_DILITHIUM_MAKE_KEY=yes
-    ENABLED_DILITHIUM_SIGN=yes
-    ENABLED_DILITHIUM_VERIFY=yes
+    ENABLED_MLDSA_MAKE_KEY=yes
+    ENABLED_MLDSA_SIGN=yes
+    ENABLED_MLDSA_VERIFY=yes
    ;;
  no)
    ;;
  all)
-    ENABLED_DILITHIUM_MAKE_KEY=yes
-    ENABLED_DILITHIUM_SIGN=yes
-    ENABLED_DILITHIUM_VERIFY=yes
+    ENABLED_MLDSA_MAKE_KEY=yes
+    ENABLED_MLDSA_SIGN=yes
+    ENABLED_MLDSA_VERIFY=yes
    ;;
  make)
-    ENABLED_DILITHIUM_MAKE_KEY=yes
+    ENABLED_MLDSA_MAKE_KEY=yes
    ;;
  sign)
-    ENABLED_DILITHIUM_SIGN=yes
+    ENABLED_MLDSA_SIGN=yes
    ;;
  verify)
-    ENABLED_DILITHIUM_VERIFY=yes
+    ENABLED_MLDSA_VERIFY=yes
    ;;
  verify-only)
-    ENABLED_DILITHIUM_MAKE_KEY=no
-    ENABLED_DILITHIUM_SIGN=no
-    ENABLED_DILITHIUM_VERIFY=yes
-    AM_CFLAGS="$AM_CFLAGS -DWOLFSSL_DILITHIUM_VERIFY_ONLY"
+    ENABLED_MLDSA_MAKE_KEY=no
+    ENABLED_MLDSA_SIGN=no
+    ENABLED_MLDSA_VERIFY=yes
+    AM_CFLAGS="$AM_CFLAGS -DWOLFSSL_MLDSA_VERIFY_ONLY"
    ;;
  small)
-    AM_CFLAGS="$AM_CFLAGS -DWOLFSSL_DILITHIUM_SMALL"
+    AM_CFLAGS="$AM_CFLAGS -DWOLFSSL_MLDSA_SMALL"
    ;;
  44)
    ENABLED_MLDSA44=yes
@@ -1869,13 +1869,13 @@ do
    ENABLED_MLDSA87=yes
    ;;
  draft|fips204-draft)
-    AM_CFLAGS="$AM_CFLAGS -DWOLFSSL_DILITHIUM_FIPS204_DRAFT"
+    AM_CFLAGS="$AM_CFLAGS -DWOLFSSL_MLDSA_FIPS204_DRAFT"
    ;;
  no-ctx)
-    AM_CFLAGS="$AM_CFLAGS -DWOLFSSL_DILITHIUM_NO_CTX"
+    AM_CFLAGS="$AM_CFLAGS -DWOLFSSL_MLDSA_NO_CTX"
    ;;
  *)
-    AC_MSG_ERROR([Invalid choice for DILITHIUM [all,make,sign,verify,verify-only,small,44,65,87,no-ctx]: $ENABLED_DILITHIUM.])
+    AC_MSG_ERROR([Invalid choice for ML-DSA [all,make,sign,verify,verify-only,small,44,65,87,no-ctx]: $ENABLED_MLDSA.])
    break;;
  esac
 done
@@ -6400,15 +6400,15 @@ AS_CASE([$FIPS_VERSION],
             ENABLED_MLKEM_ENCAPSULATE="yes"
             ENABLED_MLKEM_DECAPSULATE="yes"])

-        AS_IF([test "$ENABLED_DILITHIUM" != "yes" &&
+        AS_IF([test "$ENABLED_MLDSA" != "yes" &&
               (test "$FIPS_VERSION" != "dev" || test "$enable_dilithium" != "no")],
-            [ENABLED_DILITHIUM="yes"
+            [ENABLED_MLDSA="yes"
             ENABLED_MLDSA44="yes"
             ENABLED_MLDSA65="yes"
             ENABLED_MLDSA87="yes"
-             ENABLED_DILITHIUM_MAKE_KEY="yes"
-             ENABLED_DILITHIUM_SIGN="yes"
-             ENABLED_DILITHIUM_VERIFY="yes"])
+             ENABLED_MLDSA_MAKE_KEY="yes"
+             ENABLED_MLDSA_SIGN="yes"
+             ENABLED_MLDSA_VERIFY="yes"])

        AS_IF([test "$ENABLED_XMSS" != "yes" &&
               (test "$FIPS_VERSION" != "dev" || test "$enable_xmss" != "no")],
@@ -7330,7 +7330,7 @@ then
    ENABLED_SHAKE128=yes
    ENABLED_SHAKE256=yes
 fi
-if test "$ENABLED_DILITHIUM" != "no"
+if test "$ENABLED_MLDSA" != "no"
 then
    ENABLED_SHA3=yes
    ENABLED_SHAKE128=yes
@@ -7496,11 +7496,11 @@ then
    AM_CFLAGS="$AM_CFLAGS -DWOLFSSL_EXTRA_PQC_HYBRIDS"
 fi

-# Dilithium CFLAG processing (after FIPS section for sandwich pattern)
-if test "$ENABLED_DILITHIUM" != "no"
+# ML-DSA CFLAG processing (after FIPS section for sandwich pattern)
+if test "$ENABLED_MLDSA" != "no"
 then
-    AM_CFLAGS="$AM_CFLAGS -DHAVE_DILITHIUM"
-    AM_CCASFLAGS="$AM_CCASFLAGS -DHAVE_DILITHIUM"
+    AM_CFLAGS="$AM_CFLAGS -DWOLFSSL_HAVE_MLDSA"
+    AM_CCASFLAGS="$AM_CCASFLAGS -DWOLFSSL_HAVE_MLDSA"

    if test "$ENABLED_MLDSA44" = ""; then
        AM_CFLAGS="$AM_CFLAGS -DWOLFSSL_NO_ML_DSA_44"
@@ -7511,14 +7511,14 @@ then
    if test "$ENABLED_MLDSA87" = ""; then
        AM_CFLAGS="$AM_CFLAGS -DWOLFSSL_NO_ML_DSA_87"
    fi
-    if test "$ENABLED_DILITHIUM_MAKE_KEY" = "no"; then
-        AM_CFLAGS="$AM_CFLAGS -DWOLFSSL_DILITHIUM_NO_MAKE_KEY"
+    if test "$ENABLED_MLDSA_MAKE_KEY" = "no"; then
+        AM_CFLAGS="$AM_CFLAGS -DWOLFSSL_MLDSA_NO_MAKE_KEY"
    fi
-    if test "$ENABLED_DILITHIUM_SIGN" = "no"; then
-        AM_CFLAGS="$AM_CFLAGS -DWOLFSSL_DILITHIUM_NO_SIGN"
+    if test "$ENABLED_MLDSA_SIGN" = "no"; then
+        AM_CFLAGS="$AM_CFLAGS -DWOLFSSL_MLDSA_NO_SIGN"
    fi
-    if test "$ENABLED_DILITHIUM_VERIFY" = "no"; then
-        AM_CFLAGS="$AM_CFLAGS -DWOLFSSL_DILITHIUM_NO_VERIFY"
+    if test "$ENABLED_MLDSA_VERIFY" = "no"; then
+        AM_CFLAGS="$AM_CFLAGS -DWOLFSSL_MLDSA_NO_VERIFY"
    fi

    test "$enable_sha3" = "" && enable_sha3=yes
@@ -12214,7 +12214,7 @@ AM_CONDITIONAL([BUILD_WC_LMS],[test "x$ENABLED_LMS" != "xno" || test "x$ENABLED_
 AM_CONDITIONAL([BUILD_WC_XMSS],[test "x$ENABLED_XMSS" != "xno" || test "x$ENABLED_USERSETTINGS" = "xyes"])
 AM_CONDITIONAL([BUILD_WC_SLHDSA],[test "x$ENABLED_SLHDSA" != "xno" || test "x$ENABLED_USERSETTINGS" = "xyes"])
 AM_CONDITIONAL([BUILD_WC_MLKEM],[test "x$ENABLED_MLKEM" != "xno" || test "x$ENABLED_USERSETTINGS" = "xyes"])
-AM_CONDITIONAL([BUILD_DILITHIUM],[test "x$ENABLED_DILITHIUM" != "xno" || test "x$ENABLED_USERSETTINGS" = "xyes"])
+AM_CONDITIONAL([BUILD_MLDSA],[test "x$ENABLED_MLDSA" != "xno" || test "x$ENABLED_USERSETTINGS" = "xyes"])
 AM_CONDITIONAL([BUILD_ECCSI],[test "x$ENABLED_ECCSI" = "xyes" || test "x$ENABLED_USERSETTINGS" = "xyes"])
 AM_CONDITIONAL([BUILD_SAKKE],[test "x$ENABLED_SAKKE" = "xyes" || test "x$ENABLED_USERSETTINGS" = "xyes"])
 AM_CONDITIONAL([BUILD_MEMORY],[test "x$ENABLED_MEMORY" = "xyes" || test "x$ENABLED_USERSETTINGS" = "xyes"])
@@ -12768,7 +12768,7 @@ echo "   * LMS:                        $ENABLED_LMS"
 echo "   * XMSS:                       $ENABLED_XMSS"
 echo "   * SLH-DSA                     $ENABLED_SLHDSA"
 echo "   * MLKEM:                      $ENABLED_MLKEM"
-echo "   * DILITHIUM:                  $ENABLED_DILITHIUM"
+echo "   * ML-DSA:                     $ENABLED_MLDSA"
 echo "   * ECCSI                       $ENABLED_ECCSI"
 echo "   * SAKKE                       $ENABLED_SAKKE"
 echo "   * ASN:                        $ENABLED_ASN"
@@ -0,0 +1,192 @@
+# Dilithium → ML-DSA migration guide
+
+## Background
+
+The post-quantum signature algorithm originally implemented in wolfSSL
+under the pre-standardization name *Dilithium* was standardized by NIST
+as **ML-DSA (Module-Lattice-based Digital Signature Algorithm) — FIPS
+204** in 2024. This release renames the wolfSSL implementation of that
+algorithm to its standardized name, mirroring the earlier Kyber → ML-KEM
+migration in `wc_mlkem.{h,c}`.
+
+For application code written against the legacy `dilithium_key` /
+`wc_dilithium_*` / `wc_Dilithium_*` API there is **no immediate change
+required**: a temporary compatibility shim translates the legacy names
+into the canonical ones at compile time. The shim will be removed in a
+future release; new code should adopt the canonical names directly.
+
+## What changed
+
+### File renames
+
+| Old path                              | New path                                |
+|---------------------------------------|-----------------------------------------|
+| `wolfcrypt/src/dilithium.c`           | `wolfcrypt/src/wc_mldsa.c`              |
+| `wolfssl/wolfcrypt/dilithium.h`       | `wolfssl/wolfcrypt/wc_mldsa.h`          |
+
+The legacy `<wolfssl/wolfcrypt/dilithium.h>` path is now a thin shim
+that `#include`s `wc_mldsa.h` and provides macro / inline aliases for
+the legacy API.
+
+### Symbol renames
+
+| Old                                       | New                                          |
+|-------------------------------------------|----------------------------------------------|
+| `dilithium_key`                           | `MlDsaKey`                                   |
+| `wc_dilithium_params`                     | `MlDsaParams`                                |
+| `wc_dilithium_*` (lifecycle / sizing)     | `wc_MlDsaKey_*`                              |
+| `wc_Dilithium_*` (DER encode / decode)    | `wc_MlDsaKey_*`                              |
+| internal lower-case `dilithium_*` helpers | `mldsa_*`                                    |
+
+The 16 sign / verify / import / DER-decode entry points were also
+re-ordered to put the `MlDsaKey*` first (matching the FIPS 204 / ML-KEM
+convention used by `wc_MlKemKey_*`). The legacy parameter order is
+preserved through static-inline wrapper functions in the shim header,
+so legacy call sites compile unchanged.
+
+`wc_MlDsaKey_Init` is a 3-argument function (`MlDsaKey*`, `void* heap`,
+`int devId`) matching `wc_MlKemKey_Init`. The legacy 1-argument
+`wc_dilithium_init(key)` is mapped through the shim to
+`wc_MlDsaKey_Init(key, NULL, INVALID_DEVID)`.
+
+### Build-gate renames
+
+| Old                            | New                          |
+|--------------------------------|------------------------------|
+| `HAVE_DILITHIUM`               | `WOLFSSL_HAVE_MLDSA`         |
+| `WOLFSSL_DILITHIUM_*` (~25)    | `WOLFSSL_MLDSA_*`            |
+| `WC_DILITHIUM_CACHE_*`         | `WC_MLDSA_CACHE_*`           |
+| `WC_DILITHIUM_FIXED_ARRAY`     | `WC_MLDSA_FIXED_ARRAY`       |
+| `WC_DILITHIUMKEY_TYPE_DEFINED` | `WC_MLDSAKEY_TYPE_DEFINED`   |
+
+The Autotools / CMake configure switches gain canonical aliases:
+
+| Legacy                  | Canonical             |
+|-------------------------|-----------------------|
+| `--enable-dilithium`    | `--enable-mldsa`      |
+| `WOLFSSL_DILITHIUM`     | `WOLFSSL_MLDSA`       |
+
+Both spellings remain valid; the canonical form is recommended for new
+projects.
+
+The configure summary echoes `ML-DSA: yes` rather than `DILITHIUM: yes`.
+
+### OpenSSL compatibility
+
+The OpenSSL-compat enum value `WC_EVP_PKEY_DILITHIUM` and macro
+`EVP_PKEY_DILITHIUM` are unchanged in this release. Aligning them with
+OpenSSL 3.5+'s actual `NID_ML_DSA_*` values is planned for a follow-up
+commit.
+
+## How to migrate (when you are ready)
+
+The temporary shim accepts both legacy and canonical names indefinitely
+until it is removed. To migrate a consumer to canonical:
+
+1. Replace `#include <wolfssl/wolfcrypt/dilithium.h>` with
+   `#include <wolfssl/wolfcrypt/wc_mldsa.h>`.
+2. Replace `dilithium_key` with `MlDsaKey`.
+3. Replace each `wc_dilithium_*` / `wc_Dilithium_*` call with the
+   `wc_MlDsaKey_*` form, swapping arguments to put the key first
+   for the 16 affected entry points.
+4. Replace `HAVE_DILITHIUM` / `WOLFSSL_DILITHIUM_*` / `WC_DILITHIUM_*`
+   build-gate references with the canonical names.
+
+Migration can be done file by file; the two spellings interoperate at
+the link level (the shim's static-inline wrappers call into the
+canonical exported symbols).
+
+To suppress the legacy aliases (e.g. to surface stale references during
+migration), define one or both of:
+
+- `WOLFSSL_NO_DILITHIUM_LEGACY_NAMES` — suppresses the legacy
+  `dilithium_key` / `wc_dilithium_*` / `wc_Dilithium_*` macro / inline
+  aliases.
+- `WOLFSSL_NO_DILITHIUM_LEGACY_GATES` — suppresses the bidirectional
+  sub-config gate translations (legacy `WOLFSSL_DILITHIUM_*` /
+  `WC_DILITHIUM_*` ↔ canonical `WOLFSSL_MLDSA_*` / `WC_MLDSA_*`). The
+  parent gate (`HAVE_DILITHIUM` ↔ `WOLFSSL_HAVE_MLDSA`) forward arm is
+  always active so that builds using only the legacy parent name still
+  compile the canonical implementation file; the reverse arm honors
+  this opt-out.
+
+> **Note on `WOLFSSL_NO_DILITHIUM_LEGACY_NAMES`:** in this release the
+> opt-out is only useful for builds whose consumer code (TLS, ASN.1,
+> EVP, tests, benchmark, examples, ...) has already been migrated to
+> the canonical names. The standard wolfSSL distribution still uses
+> `wc_dilithium_*` and `dilithium_key` in `wolfcrypt/src/asn.c`,
+> `src/ssl_load.c`, `src/internal.c`, `wolfcrypt/test/test.c`, and
+> elsewhere; suppressing the macro / inline aliases breaks those
+> translation units (e.g. `wc_dilithium_verify_ctx_msg` becomes an
+> implicit declaration). The flag is intended primarily for downstream
+> projects that have completed their own migration; in-tree consumers
+> will be migrated in a follow-up PR.
+
+## Internal infrastructure files migrated to canonical sub-gates
+
+One wolfSSL-internal file outside the dilithium.h reach had its
+`WOLFSSL_DILITHIUM_NO_SIGN` / `WOLFSSL_DILITHIUM_NO_VERIFY` sub-gate
+references migrated to canonical `WOLFSSL_MLDSA_*` spellings:
+
+- `wolfssl/certs_test.h` — auto-generated cert-data buffers, has zero
+  `#include` directives. Reachable from external TUs (examples,
+  embedded apps) that pull in only `<wolfssl/ssl.h>` and do not
+  transitively include `dilithium.h`. Reads 11 sub-gate references
+  (`_NO_SIGN` / `_NO_VERIFY`).
+
+`wolfssl/wolfcrypt/memory.h` previously branched its static-pool sizing
+(`LARGEST_MEM_BUCKET` / `WOLFMEM_BUCKETS` / `WOLFMEM_DIST`) on a
+combination of `WOLFSSL_MLDSA_VERIFY_SMALL_MEM` /
+`WOLFSSL_MLDSA_SIGN_SMALL_MEM` / `WOLFSSL_MLDSA_MAKE_KEY_SMALL_MEM` /
+`WOLFSSL_MLDSA_VERIFY_ONLY`. Those branches were removed: when
+`WOLFSSL_HAVE_MLDSA` is defined, the file now picks the larger sizing
+unconditionally. The static-pool macros are consumed only by
+`wolfcrypt/src/memory.c` and the test harnesses; production deployments
+that need different sizing already override `LARGEST_MEM_BUCKET` /
+`WOLFMEM_BUCKETS` / `WOLFMEM_DIST` directly. Removing the conditional
+gating drops memory.h's dependency on ML-DSA sub-gates entirely.
+
+To keep the legacy `user_settings.h` path working for `certs_test.h` —
+i.e. a build that defines only `WOLFSSL_DILITHIUM_NO_SIGN` /
+`WOLFSSL_DILITHIUM_NO_VERIFY` and never reaches `dilithium.h` before
+the cert-buffer header is processed — the forward translations for
+those two gates live in `<wolfssl/wolfcrypt/settings.h>`. settings.h is
+included transitively by any TU that pulls in `certs_test.h`, so the
+canonical sub-gates are always defined before they are read. The
+remaining ~30 sub-gates are read only from wc\_mldsa.h / wc\_mldsa.c,
+both of which transitively pull in dilithium.h first; their forward
+translations stay there to keep settings.h lean. The reverse arm
+(canonical → legacy) lives entirely in dilithium.h because it is only
+consumed by unmigrated code, which by definition includes dilithium.h.
+The generator script (`gencertbuf.pl`) was updated correspondingly.
+
+`certs_test.h` and the `memory.h` static-pool macros are both
+wolfSSL-internal infrastructure (an auto-generated cert-buffer data
+file and the static allocator's default sizing), not consumer-facing
+API; these changes do not require downstream code changes.
+
+### Retained internal symbols
+
+A few internal-only spellings are intentionally **not** renamed in this
+PR:
+
+- `DYNAMIC_TYPE_DILITHIUM` — heap-allocation tag string used by
+  `WC_ALLOC_VAR` / `WC_FREE_VAR_EX` inside `wc_mldsa.c`. Pure
+  bookkeeping, never crosses the public API surface.
+- `ML_DSA_PCT_E` — internal error code returned only by the FIPS
+  Pairwise Consistency Test path inside `wc_MlDsaKey_MakeKey`. Not part
+  of the documented external error-code surface for this algorithm.
+
+These are scheduled for renaming alongside the eventual removal of the
+`dilithium.h` shim.
+
+## ABI note
+
+The library's exported linkage symbols are renamed: the `.so` /
+`.dylib` / `.dll` now exports `wc_MlDsaKey_*` instead of
+`wc_dilithium_*`. Applications that linked dynamically against the
+legacy symbol names need to either recompile against the legacy header
+path (the shim's static-inline wrappers resolve to the new symbols at
+compile time) or switch their sources to the canonical names. Source
+code that includes `<wolfssl/wolfcrypt/dilithium.h>` continues to build
+without modification.
@@ -3,7 +3,8 @@
 # All paths should be given relative to the root

 dist_doc_DATA+= doc/README.txt \
-	doc/QUIC.md
+	doc/QUIC.md \
+	doc/dilithium-to-mldsa-migration.md


 dox-pdf:
@@ -287,9 +287,9 @@ for (my $i = 0; $i < $num_falcon; $i++) {

 print OUT_FILE "#endif /* HAVE_FALCON */\n\n";

-# print dilithium raw keys
-print OUT_FILE "#if defined(HAVE_DILITHIUM)
-#ifndef WOLFSSL_DILITHIUM_NO_SIGN
+# print ML-DSA raw keys
+print OUT_FILE "#if defined(WOLFSSL_HAVE_MLDSA)
+#ifndef WOLFSSL_MLDSA_NO_SIGN

 /* raw private key without ASN1 syntax from
 * ./certs/dilithium/bench_dilithium_level2_key.der */
@@ -553,9 +553,9 @@ static const unsigned char bench_dilithium_level2_key[] = {
 };
 #define sizeof_bench_dilithium_level2_key (sizeof(bench_dilithium_level2_key))

-#endif /* !WOLFSSL_DILITHIUM_NO_SIGN */
+#endif /* !WOLFSSL_MLDSA_NO_SIGN */

-#ifndef WOLFSSL_DILITHIUM_NO_VERIFY
+#ifndef WOLFSSL_MLDSA_NO_VERIFY

 /* raw public key without ASN1 syntax from
 * ./certs/dilithium/bench_dilithium_level2_key.der */
@@ -696,9 +696,9 @@ static const unsigned char bench_dilithium_level2_pubkey[] = {
 #define sizeof_bench_dilithium_level2_pubkey \\
       (sizeof(bench_dilithium_level2_pubkey))

-#endif /* !WOLFSSL_DILITHIUM_NO_VERIFY */
+#endif /* !WOLFSSL_MLDSA_NO_VERIFY */

-#ifndef WOLFSSL_DILITHIUM_NO_SIGN
+#ifndef WOLFSSL_MLDSA_NO_SIGN

 /* raw private key without ASN1 syntax from
 * ./certs/dilithium/bench_dilithium_level3_key.der */
@@ -1110,9 +1110,9 @@ static const unsigned char bench_dilithium_level3_key[] = {
 };
 #define sizeof_bench_dilithium_level3_key (sizeof(bench_dilithium_level3_key))

-#endif /* !WOLFSSL_DILITHIUM_NO_SIGN */
+#endif /* !WOLFSSL_MLDSA_NO_SIGN */

-#ifndef WOLFSSL_DILITHIUM_NO_VERIFY
+#ifndef WOLFSSL_MLDSA_NO_VERIFY

 /* raw public key without ASN1 syntax from
 * ./certs/dilithium/bench_dilithium_level3_key.der */
@@ -1317,9 +1317,9 @@ static const unsigned char bench_dilithium_level3_pubkey[] = {
 static const int sizeof_bench_dilithium_level3_pubkey =
    sizeof(bench_dilithium_level3_pubkey);

-#endif /* !WOLFSSL_DILITHIUM_NO_VERIFY */
+#endif /* !WOLFSSL_MLDSA_NO_VERIFY */

-#ifndef WOLFSSL_DILITHIUM_NO_SIGN
+#ifndef WOLFSSL_MLDSA_NO_SIGN

 /* raw private key without ASN1 syntax from
 * ./certs/dilithium/bench_dilithium_level5_key.der */
@@ -1817,9 +1817,9 @@ static const unsigned char bench_dilithium_level5_key[] = {
 };
 #define sizeof_bench_dilithium_level5_key (sizeof(bench_dilithium_level5_key))

-#endif /* !WOLFSSL_DILITHIUM_NO_SIGN */
+#endif /* !WOLFSSL_MLDSA_NO_SIGN */

-#ifndef WOLFSSL_DILITHIUM_NO_VERIFY
+#ifndef WOLFSSL_MLDSA_NO_VERIFY

 /* raw public key without ASN1 syntax from
 * ./certs/dilithium/bench_dilithium_level5_key.der */
@@ -2088,16 +2088,16 @@ static const unsigned char bench_dilithium_level5_pubkey[] = {
 #define sizeof_bench_dilithium_level5_pubkey \\
       (sizeof(bench_dilithium_level5_pubkey))

-#endif /* !WOLFSSL_DILITHIUM_NO_VERIFY */
+#endif /* !WOLFSSL_MLDSA_NO_VERIFY */

-#endif /* HAVE_DILITHIUM */
+#endif /* WOLFSSL_HAVE_MLDSA */

 ";

 # ML-DSA test key material encoded per the IETF LAMPS WG profile:
 # SubjectPublicKeyInfo for public keys, PKCS#8 PrivateKeyInfo for
 # private keys, using the NIST id-ml-dsa-N OIDs.
-print OUT_FILE "#if defined(HAVE_DILITHIUM)\n\n";
+print OUT_FILE "#if defined(WOLFSSL_HAVE_MLDSA)\n\n";

 for my $L ( [44,"WOLFSSL_NO_ML_DSA_44"],
            [65,"WOLFSSL_NO_ML_DSA_65"],
@@ -2106,15 +2106,15 @@ for my $L ( [44,"WOLFSSL_NO_ML_DSA_44"],

    print OUT_FILE "#if !defined($noLevel)\n\n";

-    print OUT_FILE "#ifndef WOLFSSL_DILITHIUM_NO_VERIFY\n";
+    print OUT_FILE "#ifndef WOLFSSL_MLDSA_NO_VERIFY\n";
    print OUT_FILE "/* ./certs/mldsa/mldsa${n}_pub-spki.der */\n";
    print OUT_FILE "static const unsigned char mldsa${n}_pub_spki[] =\n{\n";
    file_to_hex("./certs/mldsa/mldsa${n}_pub-spki.der");
    print OUT_FILE "};\n";
    print OUT_FILE "#define sizeof_mldsa${n}_pub_spki (sizeof(mldsa${n}_pub_spki))\n";
-    print OUT_FILE "#endif /* !WOLFSSL_DILITHIUM_NO_VERIFY */\n\n";
+    print OUT_FILE "#endif /* !WOLFSSL_MLDSA_NO_VERIFY */\n\n";

-    print OUT_FILE "#ifndef WOLFSSL_DILITHIUM_NO_SIGN\n";
+    print OUT_FILE "#ifndef WOLFSSL_MLDSA_NO_SIGN\n";
    print OUT_FILE "/* ./certs/mldsa/mldsa${n}_priv-only.der */\n";
    print OUT_FILE "static const unsigned char mldsa${n}_priv_only[] =\n{\n";
    file_to_hex("./certs/mldsa/mldsa${n}_priv-only.der");
@@ -2132,12 +2132,12 @@ for my $L ( [44,"WOLFSSL_NO_ML_DSA_44"],
    file_to_hex("./certs/mldsa/mldsa${n}_seed-only.der");
    print OUT_FILE "};\n";
    print OUT_FILE "#define sizeof_mldsa${n}_seed_only (sizeof(mldsa${n}_seed_only))\n";
-    print OUT_FILE "#endif /* !WOLFSSL_DILITHIUM_NO_SIGN */\n\n";
+    print OUT_FILE "#endif /* !WOLFSSL_MLDSA_NO_SIGN */\n\n";

    print OUT_FILE "#endif /* !$noLevel */\n\n";
 }

-print OUT_FILE "#endif /* HAVE_DILITHIUM */\n\n";
+print OUT_FILE "#endif /* WOLFSSL_HAVE_MLDSA */\n\n";

 # convert and print 256-bit cert/keys
 print OUT_FILE "#if defined(HAVE_ECC) && defined(USE_CERT_BUFFERS_256)\n\n";
@@ -1137,8 +1137,8 @@ endif !BUILD_ARMASM_INLINE
 endif BUILD_ARMASM_NEON
 endif

-if BUILD_DILITHIUM
-src_libwolfssl@LIBSUFFIX@_la_SOURCES += wolfcrypt/src/dilithium.c
+if BUILD_MLDSA
+src_libwolfssl@LIBSUFFIX@_la_SOURCES += wolfcrypt/src/wc_mldsa.c
 if !BUILD_X86_ASM
 if BUILD_INTELASM
 src_libwolfssl@LIBSUFFIX@_la_SOURCES += wolfcrypt/src/wc_mldsa_asm.S
@@ -1817,8 +1817,8 @@ endif !BUILD_ARMASM_INLINE
 endif BUILD_ARMASM_NEON
 endif

-if BUILD_DILITHIUM
-src_libwolfssl@LIBSUFFIX@_la_SOURCES += wolfcrypt/src/dilithium.c
+if BUILD_MLDSA
+src_libwolfssl@LIBSUFFIX@_la_SOURCES += wolfcrypt/src/wc_mldsa.c
 if !BUILD_X86_ASM
 if BUILD_INTELASM
 src_libwolfssl@LIBSUFFIX@_la_SOURCES += wolfcrypt/src/wc_mldsa_asm.S
@@ -19,6 +19,17 @@
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1335, USA
 */

+/* NOTE: this file is named test_mldsa.c (canonical FIPS 204 spelling) but
+ * the test bodies still gate on legacy WOLFSSL_DILITHIUM_* names and call
+ * legacy wc_dilithium_* / dilithium_key APIs. That is intentional: the
+ * provider-side rename (Dilithium -> ML-DSA, see <wolfssl/wolfcrypt/dilithium.h>
+ * and <wolfssl/wolfcrypt/wc_mldsa.h>) keeps in-tree consumers on the
+ * pre-standardization spelling so the rename PR stays scoped to provider
+ * code only. A separate follow-up commit will migrate this file's call
+ * sites and #ifdef gates to canonical WOLFSSL_MLDSA_* / wc_MlDsaKey_*
+ * spellings; until then both spellings are kept in sync by the temporary
+ * compatibility shim in <wolfssl/wolfcrypt/dilithium.h>. */
+
 #include <tests/unit.h>

 #ifdef NO_INLINE
@@ -30423,3 +30434,284 @@ int test_mldsa_x509_pubkey_sigtype(void)
 #endif /* HAVE_DILITHIUM && OPENSSL_EXTRA && !NO_CERTS && !NO_FILESYSTEM */
    return EXPECT_RESULT();
 }
+
+/* ===========================================================================
+ * Compile-time API surface validation.
+ *
+ * The two functions below are not runtime tests. Their bodies sit inside
+ * `if (0)` so the compiler parses every reference without emitting any
+ * runtime call. Their job is to fail compilation if the canonical
+ * wc_MlDsaKey_* / MlDsaKey API in <wolfssl/wolfcrypt/wc_mldsa.h> or the
+ * legacy alias surface in <wolfssl/wolfcrypt/dilithium.h> drifts in a way
+ * that would silently break a downstream consumer. They live in this test
+ * translation unit (rather than wolfcrypt/src/wc_mldsa.c) so the library
+ * itself has no dependency on the check; the safety net only fires when
+ * `make check` is run.
+ *
+ * Storage class: GCC/Clang get __attribute__((unused, always_inline)) so
+ * unreferenced static functions don't trip -Werror=unused-function;
+ * non-GNU compilers fall back to plain static WC_INLINE.
+ * ===========================================================================
+ */
+#if defined(HAVE_DILITHIUM)
+
+#ifdef __GNUC__
+    #define WOLFSSL_MLDSA_API_CHECK_INLINE static __inline__ \
+        __attribute__((unused, always_inline))
+#else
+    #define WOLFSSL_MLDSA_API_CHECK_INLINE static WC_INLINE
+#endif
+
+/* Compile-time validation of the canonical wc_MlDsaKey_* / MlDsaKey API. */
+WOLFSSL_MLDSA_API_CHECK_INLINE void wc_mldsa_canonical_api_check(void)
+{
+    if (0) {
+        MlDsaKey k;
+        const MlDsaParams *p;
+        const byte buf[1] = { 0 };
+        word32 sz = 0;
+        byte level = 0;
+        int res = 0;
+        WC_RNG *rng = NULL;
+
+        (void)sizeof(MlDsaKey);
+        (void)sizeof(MlDsaParams);
+
+        /* Lifecycle / parameters. */
+        (void)wc_MlDsaKey_Init(&k, NULL, INVALID_DEVID);
+    #ifdef WOLF_PRIVATE_KEY_ID
+        (void)wc_MlDsaKey_InitId(&k, NULL, 0, NULL, INVALID_DEVID);
+        (void)wc_MlDsaKey_InitLabel(&k, NULL, NULL, INVALID_DEVID);
+    #endif
+    #ifndef WC_NO_CONSTRUCTORS
+        (void)wc_MlDsaKey_New(NULL, INVALID_DEVID);
+        (void)wc_MlDsaKey_Delete(&k, NULL);
+    #endif
+        wc_MlDsaKey_Free(&k);
+        (void)wc_MlDsaKey_SetParams(&k, level);
+        (void)wc_MlDsaKey_GetParams(&k, &level);
+    #ifdef WOLFSSL_MLDSA_PRIVATE_KEY
+        (void)wc_MlDsaKey_Size(&k);
+        #ifdef WOLFSSL_MLDSA_PUBLIC_KEY
+        (void)wc_MlDsaKey_PrivSize(&k);
+        #endif
+    #endif
+    #ifdef WOLFSSL_MLDSA_PUBLIC_KEY
+        (void)wc_MlDsaKey_PubSize(&k);
+    #endif
+    #if !defined(WOLFSSL_MLDSA_NO_SIGN) || !defined(WOLFSSL_MLDSA_NO_VERIFY)
+        (void)wc_MlDsaKey_SigSize(&k);
+    #endif
+    #ifdef WOLFSSL_MLDSA_CHECK_KEY
+        (void)wc_MlDsaKey_CheckKey(&k);
+    #endif
+
+        /* Length getters. */
+    #ifdef WOLFSSL_MLDSA_PRIVATE_KEY
+        (void)wc_MlDsaKey_GetPrivLen(&k, NULL);
+    #endif
+    #ifdef WOLFSSL_MLDSA_PUBLIC_KEY
+        (void)wc_MlDsaKey_GetPubLen(&k, NULL);
+    #endif
+    #if !defined(WOLFSSL_MLDSA_NO_SIGN) || !defined(WOLFSSL_MLDSA_NO_VERIFY)
+        (void)wc_MlDsaKey_GetSigLen(&k, NULL);
+    #endif
+
+        /* Make / import / export. */
+    #ifndef WOLFSSL_MLDSA_VERIFY_ONLY
+        (void)wc_MlDsaKey_MakeKey(&k, rng);
+        (void)wc_MlDsaKey_MakeKeyFromSeed(&k, NULL);
+    #endif
+    #ifdef WOLFSSL_MLDSA_PUBLIC_KEY
+        (void)wc_MlDsaKey_ImportPubRaw(&k, buf, sz);
+        (void)wc_MlDsaKey_ExportPubRaw(&k, NULL, &sz);
+    #endif
+    #ifdef WOLFSSL_MLDSA_PRIVATE_KEY
+        (void)wc_MlDsaKey_ImportPrivRaw(&k, buf, sz);
+        (void)wc_MlDsaKey_ImportKey(&k, buf, sz, buf, sz);
+        (void)wc_MlDsaKey_ExportPrivRaw(&k, NULL, &sz);
+        (void)wc_MlDsaKey_ExportKey(&k, NULL, &sz, NULL, &sz);
+    #endif
+
+        /* Sign side. */
+    #ifndef WOLFSSL_MLDSA_VERIFY_ONLY
+        #ifdef WOLFSSL_MLDSA_NO_CTX
+        (void)wc_MlDsaKey_Sign(&k, NULL, &sz, buf, sz, rng);
+        (void)wc_MlDsaKey_SignWithSeed(&k, NULL, &sz, buf, sz, NULL);
+        #endif
+        (void)wc_MlDsaKey_SignCtx(&k, NULL, 0, NULL, &sz, buf, sz, rng);
+        (void)wc_MlDsaKey_SignCtxHash(&k, NULL, 0, NULL, &sz, buf, sz, 0, rng);
+        (void)wc_MlDsaKey_SignCtxWithSeed(&k, NULL, 0, NULL, &sz, buf, sz, NULL);
+        (void)wc_MlDsaKey_SignCtxHashWithSeed(&k, NULL, 0, NULL, &sz, buf, sz, 0,
+                                              NULL);
+        (void)wc_MlDsaKey_SignMuWithSeed(&k, NULL, &sz, buf, sz, NULL);
+    #endif
+
+        /* Verify side. */
+    #ifdef WOLFSSL_MLDSA_NO_CTX
+        (void)wc_MlDsaKey_Verify(&k, buf, sz, buf, sz, &res);
+    #endif
+        (void)wc_MlDsaKey_VerifyCtx(&k, buf, sz, NULL, 0, buf, sz, &res);
+        (void)wc_MlDsaKey_VerifyCtxHash(&k, buf, sz, NULL, 0, buf, sz, 0, &res);
+        (void)wc_MlDsaKey_VerifyMu(&k, buf, sz, buf, sz, &res);
+
+        /* DER decode / encode. */
+    #ifndef WOLFSSL_MLDSA_NO_ASN1
+        #ifdef WOLFSSL_MLDSA_PRIVATE_KEY
+        (void)wc_MlDsaKey_PrivateKeyDecode(&k, buf, sz, &sz);
+        (void)wc_MlDsaKey_PrivateKeyToDer(&k, NULL, sz);
+        (void)wc_MlDsaKey_KeyToDer(&k, NULL, sz);
+        #endif
+        #ifdef WOLFSSL_MLDSA_PUBLIC_KEY
+        (void)wc_MlDsaKey_PublicKeyDecode(&k, buf, sz, &sz);
+        #endif
+        #if defined(WOLFSSL_MLDSA_PUBLIC_KEY) && \
+            defined(WC_ENABLE_ASYM_KEY_EXPORT)
+        (void)wc_MlDsaKey_PublicKeyToDer(&k, NULL, sz, 0);
+        #endif
+    #endif
+
+        /* Cross-reference: params struct field on the key. */
+        p = k.params;
+        (void)p;
+
+        (void)res;
+        (void)rng;
+        (void)sz;
+        (void)buf;
+        (void)level;
+    }
+}
+
+/* Compile-time validation of the dilithium.h legacy alias shim. */
+#if !defined(WOLFSSL_NO_DILITHIUM_LEGACY_NAMES)
+
+WOLFSSL_MLDSA_API_CHECK_INLINE void wc_mldsa_legacy_alias_check(void)
+{
+    if (0) {
+        MlDsaKey k;
+        dilithium_key *kp = (dilithium_key *)0;
+        const wc_dilithium_params *pp = (const wc_dilithium_params *)0;
+        const byte buf[1] = { 0 };
+        word32 sz = 0;
+        WC_RNG *rng = NULL;
+        int res = 0;
+        byte level = 0;
+
+        (void)kp;
+        (void)pp;
+
+        /* Type aliases. */
+        (void)sizeof(dilithium_key);
+        (void)sizeof(wc_dilithium_params);
+
+        /* No-arg-reorder lifecycle / parameters. */
+        (void)wc_dilithium_init(&k);
+        (void)wc_dilithium_init_ex(&k, NULL, INVALID_DEVID);
+    #ifdef WOLF_PRIVATE_KEY_ID
+        (void)wc_dilithium_init_id(&k, NULL, 0, NULL, INVALID_DEVID);
+        (void)wc_dilithium_init_label(&k, NULL, NULL, INVALID_DEVID);
+    #endif
+    #ifndef WC_NO_CONSTRUCTORS
+        (void)wc_dilithium_new(NULL, INVALID_DEVID);
+        (void)wc_dilithium_delete(&k, NULL);
+    #endif
+        wc_dilithium_free(&k);
+        (void)wc_dilithium_set_level(&k, level);
+        (void)wc_dilithium_get_level(&k, &level);
+    #ifdef WOLFSSL_MLDSA_PRIVATE_KEY
+        (void)wc_dilithium_size(&k);
+        #ifdef WOLFSSL_MLDSA_PUBLIC_KEY
+        (void)wc_dilithium_priv_size(&k);
+        #endif
+    #endif
+    #ifdef WOLFSSL_MLDSA_PUBLIC_KEY
+        (void)wc_dilithium_pub_size(&k);
+    #endif
+    #if !defined(WOLFSSL_MLDSA_NO_SIGN) || !defined(WOLFSSL_MLDSA_NO_VERIFY)
+        (void)wc_dilithium_sig_size(&k);
+    #endif
+    #ifdef WOLFSSL_MLDSA_CHECK_KEY
+        (void)wc_dilithium_check_key(&k);
+    #endif
+
+        /* Make / import / export (arg-reorder). */
+    #ifndef WOLFSSL_MLDSA_VERIFY_ONLY
+        (void)wc_dilithium_make_key(&k, rng);
+        (void)wc_dilithium_make_key_from_seed(&k, NULL);
+    #endif
+    #ifdef WOLFSSL_MLDSA_PUBLIC_KEY
+        (void)wc_dilithium_import_public(buf, sz, &k);
+        (void)wc_dilithium_export_public(&k, NULL, &sz);
+    #endif
+    #ifdef WOLFSSL_MLDSA_PRIVATE_KEY
+        (void)wc_dilithium_import_private(buf, sz, &k);
+        (void)wc_dilithium_import_private_only(buf, sz, &k);
+        (void)wc_dilithium_import_key(buf, sz, buf, sz, &k);
+        (void)wc_dilithium_export_private(&k, NULL, &sz);
+        (void)wc_dilithium_export_private_only(&k, NULL, &sz);
+        (void)wc_dilithium_export_key(&k, NULL, &sz, NULL, &sz);
+    #endif
+
+        /* Sign / verify (arg-reorder). */
+    #ifndef WOLFSSL_MLDSA_VERIFY_ONLY
+        #ifdef WOLFSSL_MLDSA_NO_CTX
+        (void)wc_dilithium_sign_msg(buf, sz, NULL, &sz, &k, rng);
+        (void)wc_dilithium_sign_msg_with_seed(buf, sz, NULL, &sz, &k, NULL);
+        #endif
+        (void)wc_dilithium_sign_ctx_msg(NULL, 0, buf, sz, NULL, &sz, &k, rng);
+        (void)wc_dilithium_sign_ctx_hash(NULL, 0, 0, buf, sz, NULL, &sz, &k,
+                                         rng);
+        (void)wc_dilithium_sign_ctx_msg_with_seed(NULL, 0, buf, sz, NULL, &sz,
+                                                  &k, NULL);
+        (void)wc_dilithium_sign_ctx_hash_with_seed(NULL, 0, 0, buf, sz, NULL,
+                                                   &sz, &k, NULL);
+        (void)wc_dilithium_sign_mu_with_seed(buf, sz, NULL, &sz, &k, NULL);
+    #endif
+    #ifdef WOLFSSL_MLDSA_NO_CTX
+        (void)wc_dilithium_verify_msg(buf, sz, buf, sz, &res, &k);
+    #endif
+        (void)wc_dilithium_verify_ctx_msg(buf, sz, NULL, 0, buf, sz, &res, &k);
+        (void)wc_dilithium_verify_ctx_hash(buf, sz, NULL, 0, 0, buf, sz, &res,
+                                           &k);
+        (void)wc_dilithium_verify_mu(buf, sz, buf, sz, &res, &k);
+
+        /* DER decode / encode (arg-reorder). */
+    #ifndef WOLFSSL_MLDSA_NO_ASN1
+        #ifdef WOLFSSL_MLDSA_PRIVATE_KEY
+        (void)wc_Dilithium_PrivateKeyDecode(buf, &sz, &k, sz);
+        (void)wc_Dilithium_PrivateKeyToDer(&k, NULL, sz);
+        (void)wc_Dilithium_KeyToDer(&k, NULL, sz);
+        #endif
+        #ifdef WOLFSSL_MLDSA_PUBLIC_KEY
+        (void)wc_Dilithium_PublicKeyDecode(buf, &sz, &k, sz);
+        #endif
+        #if defined(WOLFSSL_MLDSA_PUBLIC_KEY) && \
+            defined(WC_ENABLE_ASYM_KEY_EXPORT)
+        (void)wc_Dilithium_PublicKeyToDer(&k, NULL, sz, 0);
+        #endif
+    #endif
+
+        /* Internal-helper aliases (see dilithium.h). */
+    #ifndef WOLFSSL_MLDSA_NO_ASN1
+        (void)dilithium_get_oid_sum(&k, NULL);
+    #endif
+    #if !defined(WOLFSSL_MLDSA_NO_SIGN) || !defined(WOLFSSL_MLDSA_NO_VERIFY)
+        #ifndef WOLFSSL_NO_ML_DSA_44
+        wc_dilithium_encode_w1_88(NULL, NULL);
+        #endif
+        #if !defined(WOLFSSL_NO_ML_DSA_65) || !defined(WOLFSSL_NO_ML_DSA_87)
+        wc_dilithium_encode_w1_32(NULL, NULL);
+        #endif
+    #endif
+
+        (void)res;
+        (void)rng;
+        (void)sz;
+        (void)buf;
+        (void)level;
+    }
+}
+#endif /* !WOLFSSL_NO_DILITHIUM_LEGACY_NAMES */
+
+#endif /* HAVE_DILITHIUM */
@@ -9928,7 +9928,7 @@ L_sha3_block_n_avx2_rounds:
 #ifndef __APPLE__
 .size	sha3_block_n_avx2,.-sha3_block_n_avx2
 #endif /* __APPLE__ */
-#if defined(WOLFSSL_HAVE_MLKEM) || defined(HAVE_DILITHIUM) || defined(WOLFSSL_HAVE_SLHDSA)
+#if defined(WOLFSSL_HAVE_MLKEM) || defined(WOLFSSL_HAVE_MLDSA) || defined(WOLFSSL_HAVE_SLHDSA)
 #ifndef __APPLE__
 .text
 .globl	sha3_blocksx4_avx2
@@ -20664,7 +20664,7 @@ _sha3_128_blocksx4_seed_avx2:
 #ifndef __APPLE__
 .size	sha3_128_blocksx4_seed_avx2,.-sha3_128_blocksx4_seed_avx2
 #endif /* __APPLE__ */
-#endif /* defined(WOLFSSL_HAVE_MLKEM) || defined(HAVE_DILITHIUM) || defined(WOLFSSL_HAVE_SLHDSA) */
+#endif /* defined(WOLFSSL_HAVE_MLKEM) || defined(WOLFSSL_HAVE_MLDSA) || defined(WOLFSSL_HAVE_SLHDSA) */
 #ifdef WOLFSSL_HAVE_MLKEM
 #ifndef __APPLE__
 .data
@@ -26045,7 +26045,7 @@ _sha3_256_blocksx4_seed_avx2:
 .size	sha3_256_blocksx4_seed_avx2,.-sha3_256_blocksx4_seed_avx2
 #endif /* __APPLE__ */
 #endif /* WOLFSSL_HAVE_MLKEM */
-#ifdef HAVE_DILITHIUM
+#ifdef WOLFSSL_HAVE_MLDSA
 #ifndef __APPLE__
 .data
 #else
@@ -31448,7 +31448,7 @@ _sha3_256_blocksx4_seed_64_avx2:
 #ifndef __APPLE__
 .size	sha3_256_blocksx4_seed_64_avx2,.-sha3_256_blocksx4_seed_64_avx2
 #endif /* __APPLE__ */
-#endif /* HAVE_DILITHIUM */
+#endif /* WOLFSSL_HAVE_MLDSA */
 #endif /* HAVE_INTEL_AVX2 */

 #if defined(__linux__) && defined(__ELF__)
@@ -47,7 +47,7 @@
 #endif /* HAVE_INTEL_AVX2 */
 #endif /* NO_AVX2_SUPPORT */

-#ifdef HAVE_DILITHIUM
+#ifdef WOLFSSL_HAVE_MLDSA
 #ifdef HAVE_INTEL_AVX2
 #ifndef __APPLE__
 .data
@@ -35284,7 +35284,7 @@ _wc_mldsa_poly_make_pos_avx2:
 .size	wc_mldsa_poly_make_pos_avx2,.-wc_mldsa_poly_make_pos_avx2
 #endif /* __APPLE__ */
 #endif /* HAVE_INTEL_AVX2 */
-#endif /* HAVE_DILITHIUM */
+#endif /* WOLFSSL_HAVE_MLDSA */

 #if defined(__linux__) && defined(__ELF__)
 .section	.note.GNU-stack,"",%progbits
@@ -421,7 +421,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" />
@@ -244,7 +244,7 @@
 				>
 			</File>
 			<File
-				RelativePath=".\wolfcrypt\src\dilithium.c"
+				RelativePath=".\wolfcrypt\src\wc_mldsa.c"
 				>
 			</File>
 			<File
@@ -420,7 +420,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" />
@@ -4107,8 +4107,8 @@ static const unsigned char bench_falcon_level5_key[] =

 #endif /* HAVE_FALCON */

-#if defined(HAVE_DILITHIUM)
-#ifndef WOLFSSL_DILITHIUM_NO_SIGN
+#if defined(WOLFSSL_HAVE_MLDSA)
+#ifndef WOLFSSL_MLDSA_NO_SIGN

 /* raw private key without ASN1 syntax from
 * ./certs/dilithium/bench_dilithium_level2_key.der */
@@ -4372,9 +4372,9 @@ static const unsigned char bench_dilithium_level2_key[] = {
 };
 #define sizeof_bench_dilithium_level2_key (sizeof(bench_dilithium_level2_key))

-#endif /* !WOLFSSL_DILITHIUM_NO_SIGN */
+#endif /* !WOLFSSL_MLDSA_NO_SIGN */

-#ifndef WOLFSSL_DILITHIUM_NO_VERIFY
+#ifndef WOLFSSL_MLDSA_NO_VERIFY

 /* raw public key without ASN1 syntax from
 * ./certs/dilithium/bench_dilithium_level2_key.der */
@@ -4515,9 +4515,9 @@ static const unsigned char bench_dilithium_level2_pubkey[] = {
 #define sizeof_bench_dilithium_level2_pubkey \
       (sizeof(bench_dilithium_level2_pubkey))

-#endif /* !WOLFSSL_DILITHIUM_NO_VERIFY */
+#endif /* !WOLFSSL_MLDSA_NO_VERIFY */

-#ifndef WOLFSSL_DILITHIUM_NO_SIGN
+#ifndef WOLFSSL_MLDSA_NO_SIGN

 /* raw private key without ASN1 syntax from
 * ./certs/dilithium/bench_dilithium_level3_key.der */
@@ -4929,9 +4929,9 @@ static const unsigned char bench_dilithium_level3_key[] = {
 };
 #define sizeof_bench_dilithium_level3_key (sizeof(bench_dilithium_level3_key))

-#endif /* !WOLFSSL_DILITHIUM_NO_SIGN */
+#endif /* !WOLFSSL_MLDSA_NO_SIGN */

-#ifndef WOLFSSL_DILITHIUM_NO_VERIFY
+#ifndef WOLFSSL_MLDSA_NO_VERIFY

 /* raw public key without ASN1 syntax from
 * ./certs/dilithium/bench_dilithium_level3_key.der */
@@ -5136,9 +5136,9 @@ static const unsigned char bench_dilithium_level3_pubkey[] = {
 static const int sizeof_bench_dilithium_level3_pubkey =
    sizeof(bench_dilithium_level3_pubkey);

-#endif /* !WOLFSSL_DILITHIUM_NO_VERIFY */
+#endif /* !WOLFSSL_MLDSA_NO_VERIFY */

-#ifndef WOLFSSL_DILITHIUM_NO_SIGN
+#ifndef WOLFSSL_MLDSA_NO_SIGN

 /* raw private key without ASN1 syntax from
 * ./certs/dilithium/bench_dilithium_level5_key.der */
@@ -5636,9 +5636,9 @@ static const unsigned char bench_dilithium_level5_key[] = {
 };
 #define sizeof_bench_dilithium_level5_key (sizeof(bench_dilithium_level5_key))

-#endif /* !WOLFSSL_DILITHIUM_NO_SIGN */
+#endif /* !WOLFSSL_MLDSA_NO_SIGN */

-#ifndef WOLFSSL_DILITHIUM_NO_VERIFY
+#ifndef WOLFSSL_MLDSA_NO_VERIFY

 /* raw public key without ASN1 syntax from
 * ./certs/dilithium/bench_dilithium_level5_key.der */
@@ -5907,15 +5907,15 @@ static const unsigned char bench_dilithium_level5_pubkey[] = {
 #define sizeof_bench_dilithium_level5_pubkey \
       (sizeof(bench_dilithium_level5_pubkey))

-#endif /* !WOLFSSL_DILITHIUM_NO_VERIFY */
+#endif /* !WOLFSSL_MLDSA_NO_VERIFY */

-#endif /* HAVE_DILITHIUM */
+#endif /* WOLFSSL_HAVE_MLDSA */

-#if defined(HAVE_DILITHIUM)
+#if defined(WOLFSSL_HAVE_MLDSA)

 #if !defined(WOLFSSL_NO_ML_DSA_44)

-#ifndef WOLFSSL_DILITHIUM_NO_VERIFY
+#ifndef WOLFSSL_MLDSA_NO_VERIFY
 /* ./certs/mldsa/mldsa44_pub-spki.der */
 static const unsigned char mldsa44_pub_spki[] =
 {
@@ -6055,9 +6055,9 @@ static const unsigned char mldsa44_pub_spki[] =
        0xDB, 0xAA, 0x5F, 0x71
 };
 #define sizeof_mldsa44_pub_spki (sizeof(mldsa44_pub_spki))
-#endif /* !WOLFSSL_DILITHIUM_NO_VERIFY */
+#endif /* !WOLFSSL_MLDSA_NO_VERIFY */

-#ifndef WOLFSSL_DILITHIUM_NO_SIGN
+#ifndef WOLFSSL_MLDSA_NO_SIGN
 /* ./certs/mldsa/mldsa44_priv-only.der */
 static const unsigned char mldsa44_priv_only[] =
 {
@@ -6601,13 +6601,13 @@ static const unsigned char mldsa44_seed_only[] =
        0x80, 0x87, 0xA2, 0x16
 };
 #define sizeof_mldsa44_seed_only (sizeof(mldsa44_seed_only))
-#endif /* !WOLFSSL_DILITHIUM_NO_SIGN */
+#endif /* !WOLFSSL_MLDSA_NO_SIGN */

 #endif /* !WOLFSSL_NO_ML_DSA_44 */

 #if !defined(WOLFSSL_NO_ML_DSA_65)

-#ifndef WOLFSSL_DILITHIUM_NO_VERIFY
+#ifndef WOLFSSL_MLDSA_NO_VERIFY
 /* ./certs/mldsa/mldsa65_pub-spki.der */
 static const unsigned char mldsa65_pub_spki[] =
 {
@@ -6811,9 +6811,9 @@ static const unsigned char mldsa65_pub_spki[] =
        0x19, 0x0C, 0x44, 0x4C
 };
 #define sizeof_mldsa65_pub_spki (sizeof(mldsa65_pub_spki))
-#endif /* !WOLFSSL_DILITHIUM_NO_VERIFY */
+#endif /* !WOLFSSL_MLDSA_NO_VERIFY */

-#ifndef WOLFSSL_DILITHIUM_NO_SIGN
+#ifndef WOLFSSL_MLDSA_NO_SIGN
 /* ./certs/mldsa/mldsa65_priv-only.der */
 static const unsigned char mldsa65_priv_only[] =
 {
@@ -7652,13 +7652,13 @@ static const unsigned char mldsa65_seed_only[] =
        0xCB, 0xE4, 0xB1, 0x42
 };
 #define sizeof_mldsa65_seed_only (sizeof(mldsa65_seed_only))
-#endif /* !WOLFSSL_DILITHIUM_NO_SIGN */
+#endif /* !WOLFSSL_MLDSA_NO_SIGN */

 #endif /* !WOLFSSL_NO_ML_DSA_65 */

 #if !defined(WOLFSSL_NO_ML_DSA_87)

-#ifndef WOLFSSL_DILITHIUM_NO_VERIFY
+#ifndef WOLFSSL_MLDSA_NO_VERIFY
 /* ./certs/mldsa/mldsa87_pub-spki.der */
 static const unsigned char mldsa87_pub_spki[] =
 {
@@ -7926,9 +7926,9 @@ static const unsigned char mldsa87_pub_spki[] =
        0xAE, 0x60, 0x19, 0x5A
 };
 #define sizeof_mldsa87_pub_spki (sizeof(mldsa87_pub_spki))
-#endif /* !WOLFSSL_DILITHIUM_NO_VERIFY */
+#endif /* !WOLFSSL_MLDSA_NO_VERIFY */

-#ifndef WOLFSSL_DILITHIUM_NO_SIGN
+#ifndef WOLFSSL_MLDSA_NO_SIGN
 /* ./certs/mldsa/mldsa87_priv-only.der */
 static const unsigned char mldsa87_priv_only[] =
 {
@@ -8940,11 +8940,11 @@ static const unsigned char mldsa87_seed_only[] =
        0xB0, 0x87, 0x90, 0x4F
 };
 #define sizeof_mldsa87_seed_only (sizeof(mldsa87_seed_only))
-#endif /* !WOLFSSL_DILITHIUM_NO_SIGN */
+#endif /* !WOLFSSL_MLDSA_NO_SIGN */

 #endif /* !WOLFSSL_NO_ML_DSA_87 */

-#endif /* HAVE_DILITHIUM */
+#endif /* WOLFSSL_HAVE_MLDSA */

 #if defined(HAVE_ECC) && defined(USE_CERT_BUFFERS_256)

@@ -77,8 +77,17 @@ This library defines the interface APIs for X509 certificates.
    typedef struct falcon_key falcon_key;
    #define WC_FALCONKEY_TYPE_DEFINED
 #endif
-#ifndef WC_DILITHIUMKEY_TYPE_DEFINED
-    typedef struct dilithium_key dilithium_key;
+#ifndef WC_MLDSAKEY_TYPE_DEFINED
+    typedef struct MlDsaKey MlDsaKey;
+    #define WC_MLDSAKEY_TYPE_DEFINED
+#endif
+/* Legacy typedef alias. Kept until the dilithium.h compatibility shim is
+ * removed in a future release. Application code that included only
+ * <wolfssl/wolfcrypt/asn_public.h> on master continues to compile. Suppress
+ * with WOLFSSL_NO_DILITHIUM_LEGACY_NAMES. */
+#if !defined(WOLFSSL_NO_DILITHIUM_LEGACY_NAMES) && \
+    !defined(WC_DILITHIUMKEY_TYPE_DEFINED)
+    typedef struct MlDsaKey dilithium_key;
    #define WC_DILITHIUMKEY_TYPE_DEFINED
 #endif
 #ifndef WC_SLHDSAKEY_TYPE_DEFINED
@@ -76,6 +76,7 @@ nobase_include_HEADERS+= \
                         wolfssl/wolfcrypt/siphash.h \
                         wolfssl/wolfcrypt/cpuid.h \
                         wolfssl/wolfcrypt/cryptocb.h \
+                         wolfssl/wolfcrypt/wc_mldsa.h \
                         wolfssl/wolfcrypt/wc_mlkem.h \
                         wolfssl/wolfcrypt/sm2.h \
                         wolfssl/wolfcrypt/sm3.h \
@@ -133,15 +133,8 @@ WOLFSSL_API int wolfSSL_GetAllocators(wolfSSL_Malloc_cb* mf,

    #ifndef LARGEST_MEM_BUCKET
        #ifndef SESSION_CERTS
-            #ifdef HAVE_DILITHIUM
-                #if defined(WOLFSSL_DILITHIUM_VERIFY_SMALL_MEM) && \
-                    defined(WOLFSSL_DILITHIUM_SIGN_SMALL_MEM) && \
-                    defined(WOLFSSL_DILITHIUM_MAKE_KEY_SMALL_MEM) && \
-                    defined(WOLFSSL_DILITHIUM_VERIFY_ONLY)
-                    #define LARGEST_MEM_BUCKET 14000 /* Dilithium low mem */
-                #else
-                    #define LARGEST_MEM_BUCKET 131072 /* Dilithium full mem */
-                #endif
+            #ifdef WOLFSSL_HAVE_MLDSA
+                #define LARGEST_MEM_BUCKET 131072
            #else
                #define LARGEST_MEM_BUCKET 16128
            #endif
@@ -162,19 +155,10 @@ WOLFSSL_API int wolfSSL_GetAllocators(wolfSSL_Malloc_cb* mf,

    #ifndef WOLFMEM_BUCKETS
        #ifndef SESSION_CERTS
-            #ifdef HAVE_DILITHIUM
-                #if defined(WOLFSSL_DILITHIUM_VERIFY_SMALL_MEM) && \
-                    defined(WOLFSSL_DILITHIUM_SIGN_SMALL_MEM) && \
-                    defined(WOLFSSL_DILITHIUM_MAKE_KEY_SMALL_MEM) && \
-                    defined(WOLFSSL_DILITHIUM_VERIFY_ONLY)
-                    /* default size of chunks of memory to separate into */
-                    #define WOLFMEM_BUCKETS 64,128,256,512,1024,2048,4096,\
-                                           8192,LARGEST_MEM_BUCKET
-                #else
-                    /* default size of chunks of memory to separate into */
-                    #define WOLFMEM_BUCKETS 64,128,256,512,1024,8192,32768,\
-                                            65536,LARGEST_MEM_BUCKET
-                #endif
+            #ifdef WOLFSSL_HAVE_MLDSA
+                /* default size of chunks of memory to separate into */
+                #define WOLFMEM_BUCKETS 64,128,256,512,1024,8192,32768,\
+                                        65536,LARGEST_MEM_BUCKET
            #elif defined(WOLFSSL_HAVE_MLKEM)
                /* extra storage in structs for multiple attributes and order */
                #define WOLFMEM_BUCKETS 64,128,256,512,1024,2432,4096,8192,\
@@ -204,15 +188,8 @@ WOLFSSL_API int wolfSSL_GetAllocators(wolfSSL_Malloc_cb* mf,
    #endif

    #ifndef WOLFMEM_DIST
-        #ifdef HAVE_DILITHIUM
-            #if defined(WOLFSSL_DILITHIUM_VERIFY_SMALL_MEM) && \
-                defined(WOLFSSL_DILITHIUM_SIGN_SMALL_MEM) && \
-                defined(WOLFSSL_DILITHIUM_MAKE_KEY_SMALL_MEM) && \
-                defined(WOLFSSL_DILITHIUM_VERIFY_ONLY)
-                #define WOLFMEM_DIST    20,8,6,10,8,6,4,2,1
-            #else
-                #define WOLFMEM_DIST    30,10,8,15,8,10,8,5,1
-            #endif
+        #ifdef WOLFSSL_HAVE_MLDSA
+            #define WOLFMEM_DIST    30,10,8,15,8,10,8,5,1
        #elif defined(WOLFSSL_HAVE_MLKEM)
            #define WOLFMEM_DIST    49,10,6,14,5,6,14,1,1
        #elif !defined(WOLFSSL_STATIC_MEMORY_SMALL)
@@ -380,6 +380,54 @@
    #endif
 #endif

+/* Forward propagation of the legacy parent gate to the canonical name
+ * (HAVE_DILITHIUM -> WOLFSSL_HAVE_MLDSA). Always active: required so that
+ * a user_settings.h or build flag using only the legacy spelling still
+ * compiles the canonical implementation file (wc_mldsa.c) and the
+ * conditional declarations in wc_mldsa.h. */
+#ifdef HAVE_DILITHIUM
+    #ifndef WOLFSSL_HAVE_MLDSA
+        #define WOLFSSL_HAVE_MLDSA
+    #endif
+#endif
+
+/* Forward propagation of the legacy ML-DSA sub-config gates that are
+ * read by <wolfssl/certs_test.h> - the file is auto-generated by
+ * gencertbuf.pl with zero #include directives, so a TU can pull it in
+ * (transitively, via <wolfssl/ssl.h> etc.) without ever including
+ * dilithium.h. The remaining ML-DSA sub-gates are read only from
+ * wc_mldsa.h / wc_mldsa.c, both of which transitively pull in
+ * dilithium.h first; their forward translations live there.
+ * Suppressible by defining WOLFSSL_NO_DILITHIUM_LEGACY_GATES. */
+#ifndef WOLFSSL_NO_DILITHIUM_LEGACY_GATES
+    #ifdef WOLFSSL_DILITHIUM_NO_SIGN
+        #ifndef WOLFSSL_MLDSA_NO_SIGN
+            #define WOLFSSL_MLDSA_NO_SIGN
+        #endif
+    #endif
+    #ifdef WOLFSSL_DILITHIUM_NO_VERIFY
+        #ifndef WOLFSSL_MLDSA_NO_VERIFY
+            #define WOLFSSL_MLDSA_NO_VERIFY
+        #endif
+    #endif
+#endif /* !WOLFSSL_NO_DILITHIUM_LEGACY_GATES */
+
+/* Reverse propagation (WOLFSSL_HAVE_MLDSA -> HAVE_DILITHIUM). Active by
+ * default, suppressible via WOLFSSL_NO_DILITHIUM_LEGACY_GATES.
+ * Required so that <wolfssl/internal.h> and
+ * <wolfssl/wolfcrypt/cryptocb.h> (which gate their transitive include of
+ * <wolfssl/wolfcrypt/dilithium.h> on HAVE_DILITHIUM), and unmigrated
+ * consumer code that #ifdef-gates on HAVE_DILITHIUM, keep working when
+ * the user enabled ML-DSA via the canonical name only. The reverse arm
+ * of the sub-config gate translations lives in
+ * <wolfssl/wolfcrypt/dilithium.h> alongside the legacy macro / inline
+ * shims; that header is reachable through HAVE_DILITHIUM whenever the
+ * canonical gate is set. */
+#if defined(WOLFSSL_HAVE_MLDSA) && !defined(HAVE_DILITHIUM) && \
+    !defined(WOLFSSL_NO_DILITHIUM_LEGACY_GATES)
+    #define HAVE_DILITHIUM
+#endif
+
 /* Ensure WOLFSSL_DEBUG_CERTS is set when DEBUG_WOLFSSL is enabled, unless
 * expressly requested otherwise.
 */
@@ -301,7 +301,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" />
@@ -71,7 +71,7 @@ if(CONFIG_WOLFSSL)
    zephyr_library_sources(${ZEPHYR_CURRENT_MODULE_DIR}/wolfcrypt/src/curve25519.c)
    zephyr_library_sources(${ZEPHYR_CURRENT_MODULE_DIR}/wolfcrypt/src/curve448.c)
    zephyr_library_sources(${ZEPHYR_CURRENT_MODULE_DIR}/wolfcrypt/src/des3.c)
-    zephyr_library_sources(${ZEPHYR_CURRENT_MODULE_DIR}/wolfcrypt/src/dilithium.c)
+    zephyr_library_sources(${ZEPHYR_CURRENT_MODULE_DIR}/wolfcrypt/src/wc_mldsa.c)
    zephyr_library_sources(${ZEPHYR_CURRENT_MODULE_DIR}/wolfcrypt/src/dsa.c)
    zephyr_library_sources(${ZEPHYR_CURRENT_MODULE_DIR}/wolfcrypt/src/ecc_fp.c)
    zephyr_library_sources(${ZEPHYR_CURRENT_MODULE_DIR}/wolfcrypt/src/eccsi.c)