You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Rename Dilithium implementation file/symbols to ML-DSA, add backwards-compat shims
The post-quantum signature algorithm originally implemented as Dilithium
was standardized by NIST as ML-DSA in FIPS 204. This commit renames the
implementation file pair, the public API surface, and every internal
helper to the canonical ML-DSA names, mirroring the earlier Kyber ->
ML-KEM migration in wc_mlkem.{h,c}.
This commit deliberately scopes the change to the rename + compatibility
surface only. **No in-tree consumer call sites are converted.** Existing
in-tree consumers (TLS layer, ASN.1 / EVP / cryptocb wrappers, tests,
benchmark, examples, Rust wrapper) keep using the legacy spelling and
compile through the dilithium.h symbol-alias shim and the bi-directional
settings.h gate shim. New consumer code can include
<wolfssl/wolfcrypt/wc_mldsa.h> directly and use the canonical names.
Rebased onto current master (50da0c0) so that PR wolfSSL#10399's ML-DSA
Wconversion fixes (commit 2833a4b, ~220 (sword32)/(byte)/(word32)
casts in dilithium.c plus three cast hunks in asn.c) are inherited
into the new wc_mldsa.c via the file rename. The asn.c cast hunks
land separately on master and aren't part of this commit.
File layout
-----------
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 reborn as a thin
compatibility shim that #include's wc_mldsa.h and provides macro
aliases for every legacy linkage symbol.
Build-gate rename
-----------------
HAVE_DILITHIUM -> WOLFSSL_HAVE_MLDSA
WOLFSSL_DILITHIUM_* -> WOLFSSL_MLDSA_* (~25 sub-config gates)
WC_DILITHIUM_CACHE_* -> WC_MLDSA_CACHE_*
WC_DILITHIUM_FIXED_ARRAY -> WC_MLDSA_FIXED_ARRAY
WC_DILITHIUMKEY_TYPE_DEFINED -> WC_MLDSAKEY_TYPE_DEFINED
The configure summary echoes "ML-DSA: yes" rather than "DILITHIUM: yes".
The --enable-dilithium configure switch is preserved as a convenience
alias for --enable-mldsa.
A new wolfssl/wolfcrypt/settings_legacy_mldsa.h is included from
settings.h after user_settings.h. It is bi-directional: defining the
legacy gate (e.g. -DHAVE_DILITHIUM) implies the canonical gate, and
defining the canonical gate (e.g. via --enable-mldsa) implies the
legacy gate. The whole shim can be globally suppressed by defining
WOLFSSL_NO_DILITHIUM_LEGACY_GATES.
Public API rename
-----------------
Type:
dilithium_key -> MlDsaKey
Init / lifecycle (wolfSSL idiom: 1-arg simple form, 3-arg _ex form):
wc_dilithium_init -> wc_MlDsaKey_Init
wc_dilithium_init_ex -> wc_MlDsaKey_Init_ex
wc_dilithium_init_id -> wc_MlDsaKey_InitId
wc_dilithium_init_label -> wc_MlDsaKey_InitLabel
wc_dilithium_new -> wc_MlDsaKey_New
wc_dilithium_delete -> wc_MlDsaKey_Delete
wc_dilithium_free -> wc_MlDsaKey_Free
Parameters / sizing:
wc_dilithium_set_level -> wc_MlDsaKey_SetParams
wc_dilithium_get_level -> wc_MlDsaKey_GetParams
wc_dilithium_size -> wc_MlDsaKey_Size
wc_dilithium_priv_size -> wc_MlDsaKey_PrivSize
wc_dilithium_pub_size -> wc_MlDsaKey_PubSize
wc_dilithium_sig_size -> wc_MlDsaKey_SigSize
wc_dilithium_check_key -> wc_MlDsaKey_CheckKey
Key generation:
wc_dilithium_make_key -> wc_MlDsaKey_MakeKey
wc_dilithium_make_key_from_seed -> wc_MlDsaKey_MakeKeyFromSeed
Raw export (no argument reorder):
wc_dilithium_export_public -> wc_MlDsaKey_ExportPubRaw
wc_dilithium_export_private[_only] -> wc_MlDsaKey_ExportPrivRaw
wc_dilithium_export_key -> wc_MlDsaKey_ExportKey
Raw import / sign / verify / DER decode (FIPS 204 / ML-KEM
convention puts the key first; legacy form put it last):
wc_dilithium_import_public(in, inLen, key)
-> wc_MlDsaKey_ImportPubRaw(key, in, inLen)
wc_dilithium_import_private[_only](priv, privSz, key)
-> wc_MlDsaKey_ImportPrivRaw(key, priv, privSz)
wc_dilithium_import_key(priv, privSz, pub, pubSz, key)
-> wc_MlDsaKey_ImportKey(key, priv, privSz, pub, pubSz)
wc_dilithium_sign_msg / sign_ctx_msg / sign_ctx_hash / *_with_seed
-> wc_MlDsaKey_Sign / SignCtx / SignCtxHash / *WithSeed
wc_dilithium_verify_msg / verify_ctx_msg / verify_ctx_hash / verify_mu
-> wc_MlDsaKey_Verify / VerifyCtx / VerifyCtxHash / VerifyMu
wc_Dilithium_PrivateKeyDecode(in, idx, key, sz)
-> wc_MlDsaKey_PrivateKeyDecode(key, in, sz, idx)
wc_Dilithium_PublicKeyDecode(in, idx, key, sz)
-> wc_MlDsaKey_PublicKeyDecode(key, in, sz, idx)
ASN.1 encode (no reorder):
wc_Dilithium_PublicKeyToDer -> wc_MlDsaKey_PublicKeyToDer
wc_Dilithium_PrivateKeyToDer -> wc_MlDsaKey_PrivateKeyToDer
wc_Dilithium_KeyToDer -> wc_MlDsaKey_KeyToDer
OpenSSL-compat enum:
Adds WC_EVP_PKEY_MLDSA / EVP_PKEY_MLDSA. The legacy
WC_EVP_PKEY_DILITHIUM / EVP_PKEY_DILITHIUM remain as enum
aliases to the same value (no ABI change for the enum itself).
Type forward declaration in wolfssl/wolfcrypt/asn_public.h:
The 6-line forward declaration `typedef struct dilithium_key
dilithium_key;` (guarded by WC_DILITHIUMKEY_TYPE_DEFINED) is
flipped to `typedef struct MlDsaKey MlDsaKey;` (guarded by
WC_MLDSAKEY_TYPE_DEFINED).
Struct field type in wolfssl/wolfcrypt/asn.h:
The two `struct dilithium_key` references inside SignatureCtx's
ML-DSA union arm reference `struct MlDsaKey` directly. The field
name (`dilithium`) is unchanged so legacy-spelled consumer code
keeps working.
Internal helper rename
----------------------
All ~80 lower-case static / file-scope helpers in wc_mldsa.{h,c} and
wc_mldsa_asm.S are renamed dilithium_* -> mldsa_* for consistency
with ML-KEM's mlkem_* convention. The two WOLFSSL_TEST_VIS encoders
wc_dilithium_encode_w1_88/32 become wc_mldsa_encode_w1_88/32. The
struct typedef wc_dilithium_params becomes wc_mldsa_params.
The FIPS 204 spec-derived constants (DILITHIUM_Q, DILITHIUM_N,
DILITHIUM_LEVEL{2,3,5}_*, DILITHIUM_ML_DSA_{44,65,87}_*) are kept
under their existing names.
Compatibility surface
---------------------
Two independent shims, each suppressible via its own opt-out:
- The wolfssl/wolfcrypt/dilithium.h compatibility shim provides
macro aliases for every legacy linkage symbol. Direct one-to-one
#defines for the no-reorder APIs and function-like macros that
swap arguments back for the 16 arg-reorder APIs. Suppressed by
defining WOLFSSL_NO_DILITHIUM_LEGACY_NAMES.
- The wolfssl/wolfcrypt/settings_legacy_mldsa.h shim is
bi-directional: defining either spelling of any of the 32
build gates implies the other. Suppressed by defining
WOLFSSL_NO_DILITHIUM_LEGACY_GATES.
A small block of internal-helper aliases at the bottom of
dilithium.h covers WOLFSSL_LOCAL `dilithium_get_oid_sum` and the
WOLFSSL_TEST_VIS `wc_dilithium_encode_w1_*` encoders that this
branch's unmigrated in-tree consumers (src/ssl_load.c and
tests/api/test_mldsa.c) still call.
Tests / verification
--------------------
A compile-time validation block at the bottom of wc_mldsa.c (under
WOLFSSL_NO_DILITHIUM_LEGACY_NAMES suppression) exercises every
legacy macro alias. The bodies sit inside `if (0)` so the compiler
parses and type-checks the expansions without emitting any runtime
call. A missing or misordered alias produces an immediate compile
error.
Wconversion preservation: master's PR wolfSSL#10399 added 220 `(sword32)`
casts (and several `(byte)` / `(word32)` casts) inside dilithium.c.
After the file rename, the new wc_mldsa.c has all 220 `(sword32)`
casts intact (count verified equal between master's dilithium.c
and our new wc_mldsa.c).
Builds clean with --enable-mldsa and --enable-dilithium (legacy
alias). make check passes; testwolfcrypt DILITHIUM test passes.
https://claude.ai/code/session_01N9vLeZw4Gsfb11N4BU1Mbe
0 commit comments