wolfssl/doc/dilithium-to-mldsa-migration.md

# 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_*`                                    |
| `DILITHIUM_*` algorithm-parameter macros  | `MLDSA_*` (matches `MLKEM_*` in `wc_mlkem.h`) |
| `DILITHIUM_LEVEL{2,3,5}_*_SIZE`, `ML_DSA_LEVEL{2,3,5}_*_SIZE`, `DILITHIUM_ML_DSA_{44,65,87}_*_SIZE` | `WC_MLDSA_{44,65,87}_*_SIZE` |
| `DEBUG_DILITHIUM`                         | `DEBUG_MLDSA`                                |

The three legacy size-constant families
(`DILITHIUM_LEVEL{2,3,5}_*_SIZE`, `ML_DSA_LEVEL{2,3,5}_*_SIZE`,
`DILITHIUM_ML_DSA_{44,65,87}_*_SIZE`) remain reachable through the
dilithium.h shim as `#define`-style aliases for the canonical
`WC_MLDSA_{44,65,87}_*_SIZE` family — eight spellings per parameter
set (`KEY_SIZE`, `PRV_KEY_SIZE`, `PUB_KEY_SIZE`, `SIG_SIZE`,
`PRV_KEY_DER_SIZE`, `PUB_KEY_DER_SIZE`, `BOTH_KEY_DER_SIZE`,
`BOTH_KEY_PEM_SIZE`). All of them are gated on
`!defined(WOLFSSL_NO_DILITHIUM_LEGACY_NAMES)`.

The `WC_ML_DSA_{44,65,87}` / `WC_ML_DSA_{44,65,87}_DRAFT` / `WC_ML_DSA_DRAFT`
public level identifiers and the `PARAMS_ML_DSA_{44,65,87}_*`
per-parameter-set internal constants intentionally **keep** their
underscored `ML_DSA_` spelling — the level identifiers are established
public names and the `PARAMS_*` family is internal-only, so neither
benefits from a rename.

The `WOLFSSL_NO_ML_DSA_{44,65,87}` parameter-set disable gates are
likewise kept in their underscored form (matching the
`WOLFSSL_NO_ML_KEM_{512,768,1024}` spelling in `wc_mlkem.h`).

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`.

### Public error-code rename

The error-code enumerator in `wolfssl/error-ssl.h` was renamed:

| Legacy                  | Canonical            | Numeric value |
|-------------------------|----------------------|---------------|
| `DILITHIUM_KEY_SIZE_E`  | `MLDSA_KEY_SIZE_E`   | `-453` (unchanged) |

The numeric value is unchanged, so any code that compares against the
literal `-453` (or stores the value) continues to work. Code that
references the symbol by name is covered by a legacy `#define
DILITHIUM_KEY_SIZE_E MLDSA_KEY_SIZE_E` alias, gated on
`!defined(WOLFSSL_NO_DILITHIUM_LEGACY_NAMES)`. The error string returned
by `wolfSSL_ERR_reason_error_string` is now `"Wrong key size for
ML-DSA."`.

### Public ASN.1 / OID identifier renames

The pre-standardization `LEVEL2/3/5` spellings of the ML-DSA public ASN.1
key-type, certificate-type, and OID enumerators were renamed to match
the FIPS 204 parameter-set numbers (44 / 65 / 87), and to match the
existing `WC_MLDSA_{44,65,87}_*_SIZE` / `BENCH_ML_DSA_{44,65,87}_SIGN`
spellings:

| Legacy                       | Canonical              | Defined in |
|------------------------------|------------------------|------------|
| `ML_DSA_LEVEL{2,3,5}_TYPE`   | `ML_DSA_{44,65,87}_TYPE` | `wolfssl/wolfcrypt/asn_public.h` (`enum CertType`) |
| `ML_DSA_LEVEL{2,3,5}_KEY`    | `ML_DSA_{44,65,87}_KEY`  | `wolfssl/wolfcrypt/asn.h` (cert-gen key type) |
| `ML_DSA_LEVEL{2,3,5}k`       | `ML_DSA_{44,65,87}k`     | `wolfssl/wolfcrypt/oid_sum.h` (`enum Key_Sum`) |
| `CTC_ML_DSA_LEVEL{2,3,5}`    | `CTC_ML_DSA_{44,65,87}`  | `wolfssl/wolfcrypt/oid_sum.h` (`enum Ctc_SigType`) |

All four families keep their numeric values (e.g. `ML_DSA_44k` is still
`431`), so ABI is preserved. Source-level back-compat for unmigrated
consumers is provided by `#define`-style legacy aliases next to each
enum, gated on `!defined(WOLFSSL_NO_DILITHIUM_LEGACY_NAMES)` (the same
gate as the rest of the dilithium.h shim — see header comment in
`<wolfssl/wolfcrypt/dilithium.h>` for the gate's full coverage).

The `DILITHIUM_LEVEL{2,3,5}k` / `CTC_DILITHIUM_LEVEL{2,3,5}` /
`DILITHIUM_LEVEL{2,3,5}_TYPE` / `DILITHIUM_LEVEL{2,3,5}_KEY`
pre-standardization (NIST PQC round 3) enumerators are intentionally
**not** renamed: they identify a distinct draft-era OID surface and
coexist with the FIPS 204 entries in the same enum. For the same reason
the `"Dilithium Level {2,3,5}"` OID-name labels in
`wolfssl_object_info[]` (`src/ssl.c`) are kept under the Dilithium name
and coexist with parallel `"ML-DSA {44,65,87}"` rows.

The PEM header / footer markers used by `wc_MlDsaKey_*` PEM
import/export (`"-----BEGIN ML_DSA_LEVEL2 PRIVATE KEY-----"`, etc.) are
**intentionally unchanged** — the string contents are a serialization
format and renaming them would break PEM files written by older
wolfSSL. The C identifier names (`BEGIN_ML_DSA_LEVEL{2,3,5}_PRIV`,
`END_*`) are likewise unchanged.

### 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, the `ML_DSA_LEVEL{2,3,5}*` / `CTC_ML_DSA_LEVEL{2,3,5}` /
  `DILITHIUM_KEY_SIZE_E` enum aliases, and the legacy size-constant
  family (`DILITHIUM_LEVEL{2,3,5}_*_SIZE`, `ML_DSA_LEVEL{2,3,5}_*_SIZE`,
  `DILITHIUM_ML_DSA_{44,65,87}_*_SIZE`).
- `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.

In-tree consumers have been migrated to the canonical names in this
release, so a build that defines `WOLFSSL_NO_DILITHIUM_LEGACY_NAMES`
(with or without `WOLFSSL_NO_DILITHIUM_LEGACY_GATES`) compiles cleanly
and `make check` passes.

### Internal API note (no back-compat aliases)

A handful of identifiers that were defined only in wolfSSL-internal
headers (no presence in `dilithium.h`, no public-API surface) were
renamed in place **without** a backwards-compatibility alias. They
affect downstream code only if it reached into `wolfssl/internal.h` or
similar internal headers:

| Legacy                                                | Canonical                                         | Defined in |
|-------------------------------------------------------|---------------------------------------------------|------------|
| `DILITHIUM_SA_MAJOR`, `DILITHIUM_LEVEL{2,3,5}_SA_{MAJOR,MINOR}` | `MLDSA_SA_MAJOR`, `MLDSA_{44,65,87}_SA_{MAJOR,MINOR}` | `wolfssl/internal.h` |
| `SIG_DILITHIUM`                                       | `SIG_MLDSA`                                       | `wolfssl/internal.h` |
| `dilithium_level{2,3,5}_sa_algo` (`enum SignatureAlgorithm`) | `mldsa_{44,65,87}_sa_algo`                    | `wolfssl/internal.h` |
| `dilithium_sign` (`enum ClientCertificateType`)       | `mldsa_sign`                                      | `wolfssl/internal.h` |
| `MIN_DILITHIUMKEY_SZ`                                 | `MIN_MLDSAKEY_SZ`                                 | `wolfssl/internal.h` |
| `minDilithiumKeySz` (struct field on `WOLFSSL_CTX`, `WOLFSSL_CERT_MANAGER`, `Options`) | `minMlDsaKeySz`           | `wolfssl/internal.h` |
| `haveDilithiumSig` (bitfield on `WOLFSSL_CTX`, `Options`) | `haveMlDsaSig`                                | `wolfssl/internal.h` |
| `peerDilithiumKey`, `peerDilithiumKeyPresent` (`WOLFSSL`) | `peerMlDsaKey`, `peerMlDsaKeyPresent`         | `wolfssl/internal.h` |
| `HYBRID_*_DILITHIUM_LEVEL*_SA_MINOR`                  | `HYBRID_*_MLDSA_{44,65,87}_SA_MINOR`              | `src/tls13.c` (file-local) |
| `dilithium` (union field on `SignatureCtx::key`)      | `mldsa`                                           | `wolfssl/wolfcrypt/asn.h` |
| `dilithium_test` (test-driver entry point)            | `mldsa_test`                                      | `wolfcrypt/test/test.{c,h}` |
| `bench_dilithium_level{2,3,5}_{key,pubkey,sig}`       | `bench_mldsa_{44,65,87}_{key,pubkey,sig}`         | `wolfssl/certs_test.h`, `wolfcrypt/benchmark/benchmark.c` |
| `bench_dilithiumKeySign`                              | `bench_mldsaKeySign`                              | `wolfcrypt/benchmark/benchmark.{c,h}` |
| `BENCH_DILITHIUM_LEVEL{2,3,5}_SIGN`                   | `BENCH_ML_DSA_{44,65,87}_SIGN` (legacy macros deleted as redundant duplicates) | `wolfcrypt/benchmark/benchmark.c` |

The benchmark CLI options `-dilithium_level{2,3,5}` are retained as
deprecated aliases for `-ml-dsa-{44,65,87}` and will be removed
alongside the dilithium.h shim.

### Test coverage

The canonical ML-DSA API is exercised by `tests/api/test_mldsa.c`
(~24 `test_mldsa_*` functions), `wolfcrypt/test/test.c::mldsa_test`,
and the TLS / X.509 paths in `tests/api.c` that exercise ML-DSA
end-to-end. These run under all build configurations including builds
that suppress the legacy alias surface.

The legacy-name shim itself is covered by
`tests/api/test_mldsa_legacy.c::test_mldsa_legacy_shim`, a single
focused regression test combining three layers of check:

- **Compile-time `wc_static_assert`** over every alias spelling — all
  three size-constant families (LEVEL, DILITHIUM_LEVEL,
  DILITHIUM_ML_DSA) at all 8 spellings per parameter set, every public
  enum alias, the error-code alias, and the FIPS 204
  algorithm-parameter macros.
- **Typed function-pointer assignments without casts** that bind each
  symbol-form alias (`wc_dilithium_init_ex`, `wc_dilithium_free`, …) to
  a pointer with the canonical signature, so a signature drift in the
  shim trips a build error.
- **Compile-time invocation of every arg-reordering macro** under
  `if (0)` so the compiler type-checks the macro expansion in every
  configuration (including verify-only builds where the runtime smoke
  test below is skipped).
- **Runtime make-key / sign / verify / export / import / DER round-trip**
  driving the arg-reordering macros with valid inputs; a same-type arg
  swap (which the compile-time invocation can't catch) shows up as a
  verification or import failure.

The runtime portion requires both sign and verify; in a verify-only
build it skips and the compile-time layers carry the coverage. A
same-type arg swap on the verify side specifically is then caught only
by the canonical KAT-driven verify tests in
`test_mldsa.c::test_mldsa_verify_*_kats`, which always run.

The whole file becomes a `TEST_SKIPPED` stub when
`WOLFSSL_NO_DILITHIUM_LEGACY_NAMES` is defined.

## 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.