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.
Decouples the speculative key share group from preferredGroup[0]. The new
macro prefers widely deployed groups (PQ/T hybrids with X25519 or SECP256R1,
then SECP256R1/X25519/SECP384R1, then FFDHE 2048/3072) to reduce the chance
of a HelloRetryRequest, and falls back to preferredGroup[0] for
configurations not covered explicitly. Users can override the default via
user_settings.h or a manually passed -DWOLFSSL_KEY_SHARE_DEFAULT_GROUP=x via
autoconf.
Furthermore, an empty key_share is now sent when the user's group list does
not intersect preferredGroup[], keeping TLS 1.3 negotiation alive instead
of allowing a silent TLS 1.2 downgrade or handshake failure due to a
missing key share extension.
CheckOcspRequest used to return CERT_GOOD whenever a certificate
lacked an AIA extension and no override URL was configured, with
the rationale 'Cert has no OCSP URL, assuming CERT_GOOD'. That is
a fail-open soft-fail: an operator who turned on
WOLFSSL_OCSP_CHECKALL expecting every certificate in the chain to
be revocation-checked would still silently accept a certificate
that omits its OCSP responder URL, letting a misconfigured (or
attacker-controlled) issuer bypass revocation for non-stapled
flows.
Gate the fail-open path on cm->ocspCheckAll. When the caller has
asked for full-chain OCSP checking, return OCSP_NEED_URL so the
chain is refused. The legacy behavior is preserved when
ocspCheckAll is not set, keeping the soft-fail default for plain
WOLFSSL_OCSP_ENABLE users.
F-3227
wolfSSL_set_SSL_CTX is the OpenSSL-compatible entry point that an
SNI callback uses to swap in the per-vhost certificate during the
handshake. By design it only copies the certificate chain and
private key from the new CTX. Verification settings, the trusted
CA store, CRL/OCSP configuration, minimum key-size requirements,
and cipher/version policy stay attached to the original CTX. For
multi-tenant servers where each virtual host has its own security
policy, that means one host's verification rules silently apply
to a connection meant for another.
Expand the leading comment with an explicit SECURITY WARNING
that lists the settings which are NOT inherited and points at the
WOLFSSL*-level setters callers must use inside the SNI callback
when virtual hosts have different policies. The behavior of the
function is unchanged.
F-2902
When resuming a session wolfSSL_SetSession unconditionally
overwrote ssl->version with the version stored in the cached
session, even if that version was below the WOLFSSL's configured
minDowngrade. The overwritten version then fed straight into
SendClientHello, so a client configured to require TLS 1.2 or
higher could still emit a ClientHello advertising e.g. TLS 1.0
when resuming an old cached session. The ServerHello path catches
the actual downgrade, but the ClientHello version is already a
protocol-conformance issue and can confuse middleboxes.
Reject the session if its stored minor version is below
ssl->options.minDowngrade. The check is DTLS-aware: DTLS minor
versions decrease as the protocol version increases, so the
direction of the comparison is flipped for DTLS.
F-2105
DTLS minor versions decrease as the protocol version increases
(DTLS 1.0=0xFF, DTLS 1.2=0xFD, DTLS 1.3=0xFC), but the ticket
version comparisons in DoClientTicketCheckVersion used the TLS
direction unconditionally. As a result a DTLS server resuming a
session ticket from a different DTLS version could land on the
wrong branch: a ticket from a newer DTLS version would be treated
as a downgrade instead of being rejected, and a ticket from an
older DTLS version would be flagged as 'greater version' and
refused outright. The minDowngrade check at the bottom had the
same inversion bug.
Branch on ssl->options.dtls so the greater-version, lesser-version,
and minDowngrade comparisons all use the right direction for the
active protocol family. TLS behavior is unchanged.
F-1828
Server-side OCSP stapling was unconditionally folding
OCSP_CERT_REVOKED, OCSP_CERT_UNKNOWN, and OCSP_LOOKUP_FAIL into a
success result so a stapling failure would not break the handshake.
OCSP_CERT_REVOKED, however, is an explicit positive assertion of
revocation by the responder and must not be ignored: silently
suppressing it lets a server keep advertising a revoked certificate
to clients that rely on stapling for revocation status.
Drop OCSP_CERT_REVOKED from the suppression list in
CreateOcspResponse, the CSR2_OCSP_MULTI handler in
SendCertificateStatus, and ProcessChainOCSPRequest. Continue
suppressing OCSP_CERT_UNKNOWN and OCSP_LOOKUP_FAIL, which are true
soft-fail responder conditions where the responder cannot answer.
F-1820
Add bounds check before computing inputLength from curStartIdx + curSize
to prevent unsigned underflow if *inOutIdx ever exceeds the record
content boundary.
Since ProcessReply already reduces curSize by padSz after decryption,
use curStartIdx + curSize to bound content data instead of recomputing
it from buffer.length - padSz. This removes three more padSz references
from message processing code.
Move padSz index advancement from individual message handlers to a
single location at the end of record processing in ProcessReply.
Previously, each handler (DoFinished, DoApplicationData, DoAlert,
DoCertificate, DoServerHello, etc.) advanced the index by padSz,
which then had to be corrected when processing multiple messages
in one record. This "middle padding" pattern was error-prone.
Now curSize is reduced by padSz after decryption/verification so
it reflects content size only. Message handlers advance the index
by content size only. padSz is added once when the record is fully
processed. The correction code for multi-message records is removed.
- Use KEYID_SIZE for Signer key-hash comparisons since
Signer.{subject,issuer}KeyHash is sized KEYID_SIZE, not OCSP_DIGEST_SIZE.
- Rename subjectHash/issuerHash to subjectNameHash/issuerNameHash in
CheckOcspResponder/CheckOcspResponderChain to make the name-vs-key
hash distinction explicit.
- Expand the Signer.issuerKeyHash field comment to clarify it is the
subject key hash of the immediate issuer CA.
- Add an imposter-root-ca cert (same DN as root-ca, different RSA key)
for tests that need to exercise the new CertID issuerKeyHash binding.
Tobias Frauenschläger
Sean Parkinson
Eric Blankenhorn
David Garske
Kareem
JacobBarthelmeh
Paul Adelsbach
Juliusz Sosinowicz
Ruby Martin
sebastian-carpenter