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.
Refactors the output format of generated assembly files across all
platforms
(x86_64, ARM AArch64, ARMv8-32, Thumb2, PowerPC) for consistency and
correctness.
Changes
Data constant consolidation
- Pack multiple values per directive line (e.g., 4× .long or 8× .short
per
line) instead of one value per line, reducing file sizes significantly
- Normalize hex literal formatting: 64-bit values use full 8-byte
zero-padded
form (e.g., 0x0000000003ffffff instead of 0x3ffffff)
x86_64 assembly
- Use decimal immediate values for shift counts (e.g., $1 instead of
$0x01)
- .asm (MASM): use hex notation consistently for data constants;
update ALIGN
values to match data width (e.g., ALIGN 32 for 256-bit aligned data)
ARM .S files
- Move .type directive before .section for data objects (correct
ordering per
ELF convention)
ARM/Thumb2 inline C (_c.c) files
- Replace asm( with __asm__( for register variable constraints (better
portability)
- Add XALIGNED(8) attribute to constant lookup tables used in inline
asm
- Remove redundant #include <stdint.h> and
<wolfssl/wolfcrypt/libwolfssl_sources.h> headers
Files affected: 71 assembly and companion C files across
wolfcrypt/src/,
wolfcrypt/src/port/arm/, covering AES, ChaCha, Poly1305,
SHA-256/512/3,
Curve25519, ML-KEM, ML-DSA, and SP math routines.
Optimize code knowing it is for Intel x64.
Change signing to calculate one polynomial at a time so that if it isn't
valid then we fail early.
Other minor improvements.
Move the SHA-3 4 blocks at a time assembly into SHA-3 asm file.
Make constants in assembly the same length (front pad with zeros).
For the CMake and autotools flows, enabling user_settings.h will define the
macro WOLFSSL_USER_SETTINGS_ASM. This will cause the generated
user_settings_asm.h to be included in the .S assembly files. If the user is
building without autotools or CMake, these files will include user_settings.h
directly, unless WOLFSSL_USER_SETTINGS_ASM is defined.
For user_settings.h builds, .S assembly files need to include user_settings.h
in order to get the defines used by the build. However, a user_settings.h may
contain code only understood by a C compiler and not the assembler (e.g. a
typedef). This commit makes it so our autotools and CMake builds produce a file
user_settings_asm.h when doing a user_settings.h build. This generated header
contains only the preprocessor directives from the user_settings.h. As a result,
it can be safely included by our assembly code files.
Add x86_64 assembly code:
- BMI2
- AVX2 (using ymm, slower than BMI2)
- AVX2 of 4 similtaneous hashes
Add SHAKE128 functions and tests.
Add Absorb and Squeeze functions for SHAKE128 and SHAK256 and tests.
Add doxygen for SHA-3 and SHAKE functions.
Update other generated x86_64 assembly files to include settings.h.
Tobias Frauenschläger
Sean Parkinson
JacobBarthelmeh
Daniel Pouzzner
Hayden Roche