Skip to content

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

Open
Frauschi wants to merge 1 commit intowolfSSL:masterfrom
Frauschi:mldsa_rename
Open

Rename Dilithium to canonical ML-DSA (FIPS 204) names#10436
Frauschi wants to merge 1 commit intowolfSSL:masterfrom
Frauschi:mldsa_rename

Conversation

@Frauschi
Copy link
Copy Markdown
Contributor

@Frauschi Frauschi commented May 8, 2026

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-ups after this PR

After this PR, two independent follow-up PRs will be opened:

  1. Completely rename all internals in wc_dilithium{.h/.c} to "mldsa" (no external facing changes)
  2. Rename all call-sites within the library to the new names, removing the usage of the legacy shim header (except for some testing infrastructure)

@Frauschi Frauschi self-assigned this May 8, 2026
@github-actions
Copy link
Copy Markdown

github-actions Bot commented May 8, 2026

MemBrowse Memory Report

No memory changes detected for:

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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant