Skip to content

Algorithms - ML-DSA (FIPS 204)

More...

Functions

Name
int wc_MlDsaKey_Init(wc_MlDsaKey * key, void * heap, int devId)
Initializes a wc_MlDsaKey object. Must be called before any other ML_DSA operation. Use wc_MlDsaKey_Free() to release resources when done.
wc_MlDsaKey * wc_MlDsaKey_New(void * heap, int devId)
Allocates and initializes a new wc_MlDsaKey on the heap. The returned pointer must be released with wc_MlDsaKey_Delete(). Only available when wolfSSL is built without WC_NO_CONSTRUCTORS.
int wc_MlDsaKey_Delete(wc_MlDsaKey * key, wc_MlDsaKey ** key_p)
Frees and zeros a heap_allocated wc_MlDsaKey previously returned by wc_MlDsaKey_New(). On success the caller's pointer variable is set to NULL via key_p when key_p is not NULL. Only available when wolfSSL is built without WC_NO_CONSTRUCTORS.
int wc_MlDsaKey_InitId(wc_MlDsaKey * key, const unsigned char * id, int len, void * heap, int devId)
Initializes a wc_MlDsaKey with a device_side key identifier. Equivalent to wc_MlDsaKey_Init() but also stashes a binary id that a crypto callback can use to look up the underlying key material on the device. Only available when wolfSSL is built with WOLF_PRIVATE_KEY_ID.
int wc_MlDsaKey_InitLabel(wc_MlDsaKey * key, const char * label, void * heap, int devId)
Initializes a wc_MlDsaKey with a device_side key label. Equivalent to wc_MlDsaKey_Init() but also stashes a label string that a crypto callback can use to look up the underlying key material on the device. Only available when wolfSSL is built with WOLF_PRIVATE_KEY_ID.
int wc_MlDsaKey_SetParams(wc_MlDsaKey * key, byte level)
Selects the ML_DSA parameter set for this key. Must be called after wc_MlDsaKey_Init() and before key generation, signing or verifying.
int wc_MlDsaKey_GetParams(wc_MlDsaKey * key, byte * level)
Retrieves the ML-DSA parameter set currently selected on this key.
void wc_MlDsaKey_Free(wc_MlDsaKey * key)
Releases resources held by a wc_MlDsaKey. After this call the object must be re_initialized with wc_MlDsaKey_Init() before it can be used again. Safe to call with a NULL pointer.
int wc_MlDsaKey_MakeKey(wc_MlDsaKey * key, WC_RNG * rng)
Generates a new ML_DSA key pair using the provided RNG. The parameter set must already be set with wc_MlDsaKey_SetParams(). Both the public and private key components are populated on success.
int wc_MlDsaKey_MakeKeyFromSeed(wc_MlDsaKey * key, const byte * seed)
Deterministically generates an ML-DSA key pair from a 32-byte seed. Useful for known-answer tests and for applications that derive the seed from another secret. The seed buffer must contain exactly 32 bytes.
int wc_MlDsaKey_MakePublicKey(wc_MlDsaKey * key)
Derives public key for a wc_MlDsaKey with private key set. If the public key is already set, it is only checked against the private key's tr (H(pk)); use wc_MlDsaKey_CheckKey() for a full key pair check. The private key is still required: a public-only key returns BAD_FUNC_ARG. Available when WC_MLDSA_HAVE_MAKE_PUBLIC_KEY is defined: that is, when WOLFSSL_MLDSA_ASSIGN_KEY, WOLFSSL_MLDSA_NO_MAKE_KEY and WOLFSSL_MLDSA_VERIFY_ONLY are not defined.
int wc_MlDsaKey_SignCtx(wc_MlDsaKey * key, const byte * ctx, byte ctxLen, byte * sig, word32 * sigLen, const byte * msg, word32 msgLen, WC_RNG * rng)
Signs a message with ML-DSA using the FIPS 204 randomized-with-context signing API. Pass ctx=NULL and ctxLen=0 for an empty context.
int wc_MlDsaKey_SignCtxHash(wc_MlDsaKey * key, const byte * ctx, byte ctxLen, byte * sig, word32 * sigLen, const byte * hash, word32 hashLen, int hashAlg, WC_RNG * rng)
HashML-DSA signing variant: signs a pre-hashed message. The caller supplies the hash bytes and identifies the hash algorithm. This is the "pre-hash" mode of FIPS 204.
int wc_MlDsaKey_Sign(wc_MlDsaKey * key, byte * sig, word32 * sigLen, const byte * msg, word32 msgLen, WC_RNG * rng)
Legacy ML_DSA signing API without a context parameter. Only available when wolfSSL is built with WOLFSSL_MLDSA_NO_CTX. New code should call wc_MlDsaKey_SignCtx() with ctx=NULL and ctxLen=0 for a FIPS 204 compliant empty-context signature.
int wc_MlDsaKey_SignCtxWithSeed(wc_MlDsaKey * key, const byte * ctx, byte ctxLen, byte * sig, word32 * sigLen, const byte * msg, word32 msgLen, const byte * seed)
Deterministic signing variant of wc_MlDsaKey_SignCtx(). The 32-byte seed replaces the randomness an RNG would supply, so the same key/ctx/msg/seed always produces the same signature.
int wc_MlDsaKey_SignCtxHashWithSeed(wc_MlDsaKey * key, const byte * ctx, byte ctxLen, byte * sig, word32 * sigLen, const byte * hash, word32 hashLen, int hashAlg, const byte * seed)
Deterministic HashML_DSA signing: like wc_MlDsaKey_SignCtxHash() but uses the supplied 32-byte seed in place of an RNG.
int wc_MlDsaKey_SignMuWithSeed(wc_MlDsaKey * key, byte * sig, word32 * sigLen, const byte * mu, word32 muLen, const byte * seed)
Signs a pre_computed mu value (the externally derived SHAKE256 hash of (tr
int wc_MlDsaKey_SignWithSeed(wc_MlDsaKey * key, byte * sig, word32 * sigLen, const byte * msg, word32 msgLen, const byte * seed)
Legacy seed_based signing API without a context parameter. Only available when wolfSSL is built with WOLFSSL_MLDSA_NO_CTX. New code should use wc_MlDsaKey_SignCtxWithSeed().
int wc_MlDsaKey_VerifyCtx(wc_MlDsaKey * key, const byte * sig, word32 sigLen, const byte * ctx, byte ctxLen, const byte * msg, word32 msgLen, int * res)
Verifies an ML_DSA signature produced by wc_MlDsaKey_SignCtx() or one of its variants. On entry res is set to 0; on success it is set to 1 when the signature is valid and left at 0 otherwise. The function's return value reports whether verification could be carried out at all; a bad signature is NOT a function-level error.
int wc_MlDsaKey_VerifyCtxHash(wc_MlDsaKey * key, const byte * sig, word32 sigLen, const byte * ctx, byte ctxLen, const byte * hash, word32 hashLen, int hashAlg, int * res)
Verifies a HashML_DSA signature where the message digest was supplied directly. See wc_MlDsaKey_VerifyCtx() for the semantics of res.
int wc_MlDsaKey_VerifyMu(wc_MlDsaKey * key, const byte * sig, word32 sigLen, const byte * mu, word32 muLen, int * res)
Verifies a signature over a pre_computed 64_byte mu value (see wc_MlDsaKey_SignMuWithSeed()). See wc_MlDsaKey_VerifyCtx() for the semantics of res.
int wc_MlDsaKey_SetPrecompA(wc_MlDsaKey * key, const sword32 * a, word32 aLen, const byte * rho, word32 rhoLen)
Attaches a matrix A that was expanded off target, so verification can skip the SHAKE128 rejection sampling that otherwise dominates it. A is a function of the public seed rho alone, so wherever the verification key is fixed at build time - secure boot being the usual case - A can be computed once on a host and stored in flash. Available only when WOLFSSL_MLDSA_VERIFY_PRECOMP_A is defined, and honoured by both the default and the small-memory verifiers.
int wc_MlDsaKey_Verify(wc_MlDsaKey * key, const byte * sig, word32 sigLen, const byte * msg, word32 msgLen, int * res)
Legacy ML_DSA verify API without a context parameter. Only available when wolfSSL is built with WOLFSSL_MLDSA_NO_CTX. New code should use wc_MlDsaKey_VerifyCtx() with ctx=NULL and ctxLen=0.
int wc_MlDsaKey_Size(wc_MlDsaKey * key)
Returns the size in bytes of the encoded private key for the parameter set selected on this key. Equivalent to wc_MlDsaKey_PrivSize() and provided for API compatibility.
int wc_MlDsaKey_PrivSize(wc_MlDsaKey * key)
Returns the size in bytes of the encoded private key for the parameter set selected on this key.
int wc_MlDsaKey_PubSize(wc_MlDsaKey * key)
Returns the size in bytes of the encoded public key for the parameter set selected on this key.
int wc_MlDsaKey_SigSize(wc_MlDsaKey * key)
Returns the size in bytes of the signature produced by this key's parameter set.
int wc_MlDsaKey_GetPrivLen(wc_MlDsaKey * key, int * len)
Writes the encoded private key size into *len. Equivalent information to wc_MlDsaKey_PrivSize() but uses an out-parameter style.
int wc_MlDsaKey_GetPubLen(wc_MlDsaKey * key, int * len)
Writes the encoded public key size into *len. Equivalent information to wc_MlDsaKey_PubSize() but uses an out-parameter style.
int wc_MlDsaKey_GetSigLen(wc_MlDsaKey * key, int * len)
Writes the signature size into *len. Equivalent information to wc_MlDsaKey_SigSize() but uses an out-parameter style.
int wc_MlDsaKey_CheckKey(wc_MlDsaKey * key)
Self-checks an ML-DSA key by recomputing the public key from the private and comparing against the stored public. Only available when wolfSSL is built with WOLFSSL_MLDSA_CHECK_KEY.
int wc_MlDsaKey_ImportPubRaw(wc_MlDsaKey * key, const byte * in, word32 inLen)
Imports a raw ML_DSA public key. The parameter set must already be selected on the key. inLen must match the size returned by wc_MlDsaKey_PubSize() for the selected parameter set.
int wc_MlDsaKey_ImportPrivRaw(wc_MlDsaKey * key, const byte * priv, word32 privSz)
Imports a raw ML_DSA private key. The parameter set must already be selected. privSz must match the size returned by wc_MlDsaKey_PrivSize().
int wc_MlDsaKey_ImportKey(wc_MlDsaKey * key, const byte * priv, word32 privSz, const byte * pub, word32 pubSz)
Imports a raw ML_DSA key pair (private and public parts together). The parameter set must already be selected.
int wc_MlDsaKey_ExportPubRaw(wc_MlDsaKey * key, byte * out, word32 * outLen)
Exports the raw ML-DSA public key. On entry *outLen is the size of out; on success it is updated to the bytes written.
int wc_MlDsaKey_ExportPrivRaw(wc_MlDsaKey * key, byte * out, word32 * outLen)
Exports the raw ML-DSA private key. On entry *outLen is the size of out; on success it is updated to the bytes written.
int wc_MlDsaKey_ExportKey(wc_MlDsaKey * key, byte * priv, word32 * privSz, byte * pub, word32 * pubSz)
Exports both raw public and private ML-DSA key components in one call.
int wc_MlDsaKey_PrivateKeyDecode(wc_MlDsaKey * key, const byte * input, word32 inSz, word32 * inOutIdx)
Parses an ML_DSA private key from a DER/ASN.1 encoded buffer (PKCS#8 OneAsymmetricKey). The parameter set is inferred from the algorithm identifier in the encoding, so it does NOT need to be set beforehand. On success *inOutIdx is advanced past the consumed bytes.
int wc_MlDsaKey_PublicKeyDecode(wc_MlDsaKey * key, const byte * input, word32 inSz, word32 * inOutIdx)
Parses an ML_DSA public key from a DER/ASN.1 encoded buffer (SubjectPublicKeyInfo). The parameter set is inferred from the algorithm identifier. On success *inOutIdx is advanced past the consumed bytes.
int wc_MlDsaKey_PublicKeyToDer(wc_MlDsaKey * key, byte * output, word32 inLen, int withAlg)
Encodes an ML_DSA public key to DER. When withAlg is non_zero the output is a full SubjectPublicKeyInfo (with AlgorithmIdentifier); when zero the output is the raw public key bytes.
int wc_MlDsaKey_KeyToDer(wc_MlDsaKey * key, byte * output, word32 inLen)
Encodes an ML_DSA key pair (public + private) to DER as a PKCS#8 OneAsymmetricKey structure. Pass NULL as output to query the required buffer size.
int wc_MlDsaKey_PrivateKeyToDer(wc_MlDsaKey * key, byte * output, word32 inLen)
Encodes the ML_DSA private key to DER. Per FIPS 204 the private key encoding includes the public component, so this function is currently an alias of wc_MlDsaKey_KeyToDer() kept for API parity with other algorithms.

Detailed Description

ML-DSA (Module-Lattice-based Digital Signature Algorithm) is a quantum-resistant digital signature scheme standardized by NIST as FIPS 204. The pre-standardization name was Dilithium; legacy Dilithium type and macro names remain as aliases for unmigrated consumer code (see ).

ML-DSA defines three parameter sets identified by NIST security category: ML-DSA-44 (level 2), ML-DSA-65 (level 3) and ML-DSA-87 (level 5). All three are supported by the same wc_MlDsaKey object; the parameter set is selected with wc_MlDsaKey_SetParams().

Functions Documentation

function wc_MlDsaKey_Init

int wc_MlDsaKey_Init(
    wc_MlDsaKey * key,
    void * heap,
    int devId
)

Initializes a wc_MlDsaKey object. Must be called before any other ML-DSA operation. Use wc_MlDsaKey_Free() to release resources when done.

Parameters:

  • key Pointer to the wc_MlDsaKey to initialize.
  • heap Heap hint for dynamic memory allocation. May be NULL.
  • devId Device identifier for hardware crypto callbacks. Use INVALID_DEVID for software-only.

See:

Return:

  • 0 on success.
  • BAD_FUNC_ARG if key is NULL.
  • Other negative value if initializing the key's SHAKE-256 object fails.

ML-DSA (FIPS 204) is a quantum-resistant digital signature algorithm. Three parameter sets are defined and selected via wc_MlDsaKey_SetParams() after init:

  • WC_ML_DSA_44 (NIST security level 2),
  • WC_ML_DSA_65 (level 3),
  • WC_ML_DSA_87 (level 5).

Example

wc_MlDsaKey key;
int ret;

ret = wc_MlDsaKey_Init(&key, NULL, INVALID_DEVID);
if (ret != 0) {
    // error initializing key
}
ret = wc_MlDsaKey_SetParams(&key, WC_ML_DSA_65);
// ... use key ...
wc_MlDsaKey_Free(&key);

function wc_MlDsaKey_New

wc_MlDsaKey * wc_MlDsaKey_New(
    void * heap,
    int devId
)

Allocates and initializes a new wc_MlDsaKey on the heap. The returned pointer must be released with wc_MlDsaKey_Delete(). Only available when wolfSSL is built without WC_NO_CONSTRUCTORS.

Parameters:

  • heap Heap hint for dynamic memory allocation. May be NULL.
  • devId Device identifier for hardware crypto callbacks. Use INVALID_DEVID for software-only.

See:

Return:

  • Pointer to a freshly allocated wc_MlDsaKey on success.
  • NULL on allocation failure.

Example

wc_MlDsaKey* key = wc_MlDsaKey_New(NULL, INVALID_DEVID);
if (key == NULL) {
    // allocation failed
}
// ... use key ...
wc_MlDsaKey_Delete(key, &key);

function wc_MlDsaKey_Delete

int wc_MlDsaKey_Delete(
    wc_MlDsaKey * key,
    wc_MlDsaKey ** key_p
)

Frees and zeros a heap-allocated wc_MlDsaKey previously returned by wc_MlDsaKey_New(). On success the caller's pointer variable is set to NULL via key_p when key_p is not NULL. Only available when wolfSSL is built without WC_NO_CONSTRUCTORS.

Parameters:

  • key The wc_MlDsaKey to free.
  • key_p Optional address of the caller's pointer variable; when not NULL, it is set to NULL on success.

See: wc_MlDsaKey_New

Return:

  • 0 on success.
  • BAD_FUNC_ARG if key is NULL.

function wc_MlDsaKey_InitId

int wc_MlDsaKey_InitId(
    wc_MlDsaKey * key,
    const unsigned char * id,
    int len,
    void * heap,
    int devId
)

Initializes a wc_MlDsaKey with a device-side key identifier. Equivalent to wc_MlDsaKey_Init() but also stashes a binary id that a crypto callback can use to look up the underlying key material on the device. Only available when wolfSSL is built with WOLF_PRIVATE_KEY_ID.

Parameters:

  • key Pointer to the wc_MlDsaKey to initialize.
  • id Pointer to the device-side key identifier bytes. May be NULL when len is 0.
  • len Number of bytes in id; must be in [0, MLDSA_MAX_ID_LEN].
  • heap Heap hint for dynamic memory allocation. May be NULL.
  • devId Device identifier for the crypto callback. Should be a registered cb devId, not INVALID_DEVID.

See:

Return:

  • 0 on success.
  • BAD_FUNC_ARG if key is NULL, or if id is NULL and len is positive.
  • BUFFER_E if len is negative or exceeds MLDSA_MAX_ID_LEN.

The id is copied into the key object; the caller may free its buffer immediately after this call returns.

The key is given the highest parameter set compiled in (WC_ML_DSA_87 unless it was disabled at build time), as the parameter set of the key held on the device is not known here. Call wc_MlDsaKey_SetParams() to select a different one.

function wc_MlDsaKey_InitLabel

int wc_MlDsaKey_InitLabel(
    wc_MlDsaKey * key,
    const char * label,
    void * heap,
    int devId
)

Initializes a wc_MlDsaKey with a device-side key label. Equivalent to wc_MlDsaKey_Init() but also stashes a label string that a crypto callback can use to look up the underlying key material on the device. Only available when wolfSSL is built with WOLF_PRIVATE_KEY_ID.

Parameters:

  • key Pointer to the wc_MlDsaKey to initialize.
  • label NUL-terminated device-side key label string.
  • heap Heap hint for dynamic memory allocation. May be NULL.
  • devId Device identifier for the crypto callback.

See:

Return:

  • 0 on success.
  • BAD_FUNC_ARG if key or label is NULL.
  • BUFFER_E if label is empty or longer than MLDSA_MAX_LABEL_LEN.

The label length is taken via XSTRLEN, so embedded NUL bytes terminate the label.

The parameter set is chosen as in wc_MlDsaKey_InitId().

function wc_MlDsaKey_SetParams

int wc_MlDsaKey_SetParams(
    wc_MlDsaKey * key,
    byte level
)

Selects the ML-DSA parameter set for this key. Must be called after wc_MlDsaKey_Init() and before key generation, signing or verifying.

Parameters:

  • key Pointer to an initialized wc_MlDsaKey.
  • level Parameter set: WC_ML_DSA_44, WC_ML_DSA_65 or WC_ML_DSA_87.

See:

Return:

  • 0 on success.
  • BAD_FUNC_ARG if key is NULL or level is not a recognized parameter set.
  • NOT_COMPILED_IN if level names a parameter set that was disabled at build time.

function wc_MlDsaKey_GetParams

int wc_MlDsaKey_GetParams(
    wc_MlDsaKey * key,
    byte * level
)

Retrieves the ML-DSA parameter set currently selected on this key.

Parameters:

  • key Pointer to an initialized wc_MlDsaKey.
  • level Receives WC_ML_DSA_44, WC_ML_DSA_65 or WC_ML_DSA_87.

See: wc_MlDsaKey_SetParams

Return:

  • 0 on success.
  • BAD_FUNC_ARG if key or level is NULL.

function wc_MlDsaKey_Free

void wc_MlDsaKey_Free(
    wc_MlDsaKey * key
)

Releases resources held by a wc_MlDsaKey. After this call the object must be re-initialized with wc_MlDsaKey_Init() before it can be used again. Safe to call with a NULL pointer.

Parameters:

  • key Pointer to the wc_MlDsaKey to free.

See: wc_MlDsaKey_Init

function wc_MlDsaKey_MakeKey

int wc_MlDsaKey_MakeKey(
    wc_MlDsaKey * key,
    WC_RNG * rng
)

Generates a new ML-DSA key pair using the provided RNG. The parameter set must already be set with wc_MlDsaKey_SetParams(). Both the public and private key components are populated on success.

Parameters:

  • key Pointer to a wc_MlDsaKey with parameters set.
  • rng Pointer to an initialized WC_RNG.

See:

Return:

  • 0 on success.
  • BAD_FUNC_ARG if key or rng is NULL.
  • MEMORY_E on allocation failure.

Example

wc_MlDsaKey key;
WC_RNG rng;

wc_MlDsaKey_Init(&key, NULL, INVALID_DEVID);
wc_MlDsaKey_SetParams(&key, WC_ML_DSA_65);
wc_InitRng(&rng);

if (wc_MlDsaKey_MakeKey(&key, &rng) != 0) {
    // error generating key pair
}

function wc_MlDsaKey_MakeKeyFromSeed

int wc_MlDsaKey_MakeKeyFromSeed(
    wc_MlDsaKey * key,
    const byte * seed
)

Deterministically generates an ML-DSA key pair from a 32-byte seed. Useful for known-answer tests and for applications that derive the seed from another secret. The seed buffer must contain exactly 32 bytes.

Parameters:

  • key Pointer to a wc_MlDsaKey with parameters set.
  • seed Pointer to a 32-byte seed buffer.

See: wc_MlDsaKey_MakeKey

Return:

  • 0 on success.
  • BAD_FUNC_ARG if key or seed is NULL.

function wc_MlDsaKey_MakePublicKey

int wc_MlDsaKey_MakePublicKey(
    wc_MlDsaKey * key
)

Derives public key for a wc_MlDsaKey with private key set. If the public key is already set, it is only checked against the private key's tr (H(pk)); use wc_MlDsaKey_CheckKey() for a full key pair check. The private key is still required: a public-only key returns BAD_FUNC_ARG. Available when WC_MLDSA_HAVE_MAKE_PUBLIC_KEY is defined: that is, when WOLFSSL_MLDSA_ASSIGN_KEY, WOLFSSL_MLDSA_NO_MAKE_KEY and WOLFSSL_MLDSA_VERIFY_ONLY are not defined.

Parameters:

  • key Pointer to wc_MlDsaKey.

See:

Return:

  • 0 on success or already set.
  • BAD_FUNC_ARG if invalid args or the private key is not set.
  • MEMORY_E on allocation failure.
  • PUBLIC_KEY_E if the public key does not match the private key's tr or, when derived, its t0.
  • NO_VALID_DEVID with WOLF_CRYPTO_CB_ONLY_MLDSA.
  • Other negative on error.

Derivation is always done in software from the local private key bytes, including for a key initialized with a devId: a key whose private key was imported with wc_MlDsaKey_ImportPrivRaw() (or generated in software) derives normally. A key that only references a private key held on a device (wc_MlDsaKey_InitId() / wc_MlDsaKey_InitLabel()) has no local private bytes, so it returns BAD_FUNC_ARG. On PUBLIC_KEY_E an already set public key is left in place; set the matching public key, or re-initialize the key, before deriving.

function wc_MlDsaKey_SignCtx

int wc_MlDsaKey_SignCtx(
    wc_MlDsaKey * key,
    const byte * ctx,
    byte ctxLen,
    byte * sig,
    word32 * sigLen,
    const byte * msg,
    word32 msgLen,
    WC_RNG * rng
)

Signs a message with ML-DSA using the FIPS 204 randomized-with-context signing API. Pass ctx=NULL and ctxLen=0 for an empty context.

Parameters:

  • key Pointer to a wc_MlDsaKey with the private key.
  • ctx Optional context string (may be NULL when ctxLen=0).
  • ctxLen Length of ctx in bytes; must be 0 when ctx is NULL, and no greater than 255.
  • sig Buffer that receives the signature.
  • sigLen In: size of sig. Out: bytes written.
  • msg Message to sign.
  • msgLen Length of msg in bytes.
  • rng Pointer to an initialized WC_RNG.

See:

Return:

  • 0 on success.
  • BAD_FUNC_ARG if any required pointer is NULL, ctxLen is invalid or the key has no private key set.
  • BUFFER_E if the sig buffer is too small.

On entry *sigLen is the size of the sig buffer; on success it is updated to the number of bytes written. Use wc_MlDsaKey_SigSize() or wc_MlDsaKey_GetSigLen() to determine the required buffer size.

function wc_MlDsaKey_SignCtxHash

int wc_MlDsaKey_SignCtxHash(
    wc_MlDsaKey * key,
    const byte * ctx,
    byte ctxLen,
    byte * sig,
    word32 * sigLen,
    const byte * hash,
    word32 hashLen,
    int hashAlg,
    WC_RNG * rng
)

HashML-DSA signing variant: signs a pre-hashed message. The caller supplies the hash bytes and identifies the hash algorithm. This is the "pre-hash" mode of FIPS 204.

Parameters:

  • key Pointer to a wc_MlDsaKey with the private key.
  • ctx Optional context string (NULL when ctxLen=0).
  • ctxLen Length of ctx in bytes; no greater than 255.
  • sig Buffer that receives the signature.
  • sigLen In: size of sig. Out: bytes written.
  • hash The message digest to sign.
  • hashLen Length of hash in bytes.
  • hashAlg Hash algorithm identifier (e.g. WC_HASH_TYPE_SHA256).
  • rng Pointer to an initialized WC_RNG.

See:

Return:

  • 0 on success.
  • BAD_FUNC_ARG if any required pointer is NULL, ctxLen is invalid, hashAlg is not supported or is weaker than the parameter set (FIPS 204 sec 5.4), or the key has no private key set.
  • BUFFER_E if the sig buffer is too small.

Note: WOLFSSL_MLDSA_ALLOW_WEAK_PREHASH accepts a supported hash weaker than the parameter set instead of returning BAD_FUNC_ARG. An unsupported hash is still refused. Not FIPS 204 section 5.4 compliant.

function wc_MlDsaKey_Sign

int wc_MlDsaKey_Sign(
    wc_MlDsaKey * key,
    byte * sig,
    word32 * sigLen,
    const byte * msg,
    word32 msgLen,
    WC_RNG * rng
)

Legacy ML-DSA signing API without a context parameter. Only available when wolfSSL is built with WOLFSSL_MLDSA_NO_CTX. New code should call wc_MlDsaKey_SignCtx() with ctx=NULL and ctxLen=0 for a FIPS 204 compliant empty-context signature.

Parameters:

  • key Pointer to a wc_MlDsaKey with the private key.
  • sig Buffer that receives the signature.
  • sigLen In: size of sig. Out: bytes written.
  • msg Message to sign.
  • msgLen Length of msg in bytes.
  • rng Pointer to an initialized WC_RNG.

See:

Return: See wc_MlDsaKey_SignCtx().

function wc_MlDsaKey_SignCtxWithSeed

int wc_MlDsaKey_SignCtxWithSeed(
    wc_MlDsaKey * key,
    const byte * ctx,
    byte ctxLen,
    byte * sig,
    word32 * sigLen,
    const byte * msg,
    word32 msgLen,
    const byte * seed
)

Deterministic signing variant of wc_MlDsaKey_SignCtx(). The 32-byte seed replaces the randomness an RNG would supply, so the same key/ctx/msg/seed always produces the same signature.

Parameters:

  • key Pointer to a wc_MlDsaKey with the private key.
  • ctx Optional context string (NULL when ctxLen=0).
  • ctxLen Length of ctx; no greater than 255.
  • sig Buffer that receives the signature.
  • sigLen In: size of sig. Out: bytes written.
  • msg Message to sign.
  • msgLen Length of msg in bytes.
  • seed 32-byte seed bytes.

See:

Return: See wc_MlDsaKey_SignCtx().

function wc_MlDsaKey_SignCtxHashWithSeed

int wc_MlDsaKey_SignCtxHashWithSeed(
    wc_MlDsaKey * key,
    const byte * ctx,
    byte ctxLen,
    byte * sig,
    word32 * sigLen,
    const byte * hash,
    word32 hashLen,
    int hashAlg,
    const byte * seed
)

Deterministic HashML-DSA signing: like wc_MlDsaKey_SignCtxHash() but uses the supplied 32-byte seed in place of an RNG.

Parameters:

  • key Pointer to a wc_MlDsaKey with the private key.
  • ctx Optional context string (NULL when ctxLen=0).
  • ctxLen Length of ctx; no greater than 255.
  • sig Buffer that receives the signature.
  • sigLen In: size of sig. Out: bytes written.
  • hash The message digest to sign.
  • hashLen Length of hash in bytes.
  • hashAlg Hash algorithm identifier.
  • seed 32-byte seed bytes.

See: wc_MlDsaKey_SignCtxHash

Return: See wc_MlDsaKey_SignCtxHash().

function wc_MlDsaKey_SignMuWithSeed

int wc_MlDsaKey_SignMuWithSeed(
    wc_MlDsaKey * key,
    byte * sig,
    word32 * sigLen,
    const byte * mu,
    word32 muLen,
    const byte * seed
)

Signs a pre-computed mu value (the externally derived SHAKE256 hash of (tr || ctx || msg) per FIPS 204) using a deterministic 32-byte seed. Used by protocols that need to split the message-hashing step from the signing step.

Parameters:

  • key Pointer to a wc_MlDsaKey with the private key.
  • sig Buffer that receives the signature.
  • sigLen In: size of sig. Out: bytes written.
  • mu The 64-byte mu value (SHAKE256 output).
  • muLen Length of mu; must be 64.
  • seed 32-byte seed bytes.

See: wc_MlDsaKey_VerifyMu

Return:

  • 0 on success.
  • BAD_FUNC_ARG if any required pointer is NULL, muLen is not 64 or the key has no private key set.
  • BUFFER_E if the sig buffer is too small.

function wc_MlDsaKey_SignWithSeed

int wc_MlDsaKey_SignWithSeed(
    wc_MlDsaKey * key,
    byte * sig,
    word32 * sigLen,
    const byte * msg,
    word32 msgLen,
    const byte * seed
)

Legacy seed-based signing API without a context parameter. Only available when wolfSSL is built with WOLFSSL_MLDSA_NO_CTX. New code should use wc_MlDsaKey_SignCtxWithSeed().

Parameters:

  • key Pointer to a wc_MlDsaKey with the private key.
  • sig Buffer that receives the signature.
  • sigLen In: size of sig. Out: bytes written.
  • msg Message to sign.
  • msgLen Length of msg in bytes.
  • seed 32-byte seed bytes.

See: wc_MlDsaKey_SignCtxWithSeed

Return: See wc_MlDsaKey_SignCtxWithSeed().

function wc_MlDsaKey_VerifyCtx

int wc_MlDsaKey_VerifyCtx(
    wc_MlDsaKey * key,
    const byte * sig,
    word32 sigLen,
    const byte * ctx,
    byte ctxLen,
    const byte * msg,
    word32 msgLen,
    int * res
)

Verifies an ML-DSA signature produced by wc_MlDsaKey_SignCtx() or one of its variants. On entry res is set to 0; on success it is set to 1 when the signature is valid and left at 0 otherwise. The function's return value reports whether verification could be carried out at all; a bad signature is NOT a function-level error.

Parameters:

  • key Pointer to a wc_MlDsaKey with the public key.
  • sig Signature bytes to verify.
  • sigLen Length of sig in bytes.
  • ctx Optional context string (NULL when ctxLen=0).
  • ctxLen Length of ctx; no greater than 255.
  • msg Message that was signed.
  • msgLen Length of msg in bytes.
  • res Set to 1 on a valid signature, 0 otherwise.

See:

Return:

  • 0 if verification completed (check res for the result).
  • BAD_FUNC_ARG if any required pointer is NULL or ctxLen is invalid.

function wc_MlDsaKey_VerifyCtxHash

int wc_MlDsaKey_VerifyCtxHash(
    wc_MlDsaKey * key,
    const byte * sig,
    word32 sigLen,
    const byte * ctx,
    byte ctxLen,
    const byte * hash,
    word32 hashLen,
    int hashAlg,
    int * res
)

Verifies a HashML-DSA signature where the message digest was supplied directly. See wc_MlDsaKey_VerifyCtx() for the semantics of res.

Parameters:

  • key Pointer to a wc_MlDsaKey with the public key.
  • sig Signature bytes to verify.
  • sigLen Length of sig in bytes.
  • ctx Optional context string (NULL when ctxLen=0).
  • ctxLen Length of ctx; no greater than 255.
  • hash The message digest that was signed.
  • hashLen Length of hash in bytes.
  • hashAlg Hash algorithm identifier.
  • res Set to 1 on a valid signature, 0 otherwise.

See:

Return:

  • 0 if verification completed (check res for the result).
  • BAD_FUNC_ARG if any required pointer is NULL, ctxLen is invalid, or hashAlg is unsupported or weaker than the parameter set (FIPS 204 sec 5.4).

Note: WOLFSSL_MLDSA_ALLOW_WEAK_PREHASH verifies such a signature rather than refusing it. An unsupported hash is still refused.

function wc_MlDsaKey_VerifyMu

int wc_MlDsaKey_VerifyMu(
    wc_MlDsaKey * key,
    const byte * sig,
    word32 sigLen,
    const byte * mu,
    word32 muLen,
    int * res
)

Verifies a signature over a pre-computed 64-byte mu value (see wc_MlDsaKey_SignMuWithSeed()). See wc_MlDsaKey_VerifyCtx() for the semantics of res.

Parameters:

  • key Pointer to a wc_MlDsaKey with the public key.
  • sig Signature bytes to verify.
  • sigLen Length of sig in bytes.
  • mu The 64-byte mu value.
  • muLen Length of mu; must be 64.
  • res Set to 1 on a valid signature, 0 otherwise.

See: wc_MlDsaKey_SignMuWithSeed

Return:

  • 0 if verification completed (check res for the result).
  • BAD_FUNC_ARG if any required pointer is NULL or muLen is not 64.

function wc_MlDsaKey_SetPrecompA

int wc_MlDsaKey_SetPrecompA(
    wc_MlDsaKey * key,
    const sword32 * a,
    word32 aLen,
    const byte * rho,
    word32 rhoLen
)

Attaches a matrix A that was expanded off target, so verification can skip the SHAKE128 rejection sampling that otherwise dominates it. A is a function of the public seed rho alone, so wherever the verification key is fixed at build time - secure boot being the usual case - A can be computed once on a host and stored in flash. Available only when WOLFSSL_MLDSA_VERIFY_PRECOMP_A is defined, and honoured by both the default and the small-memory verifiers.

Parameters:

  • key Pointer to a wc_MlDsaKey holding the public key.
  • a Expanded matrix A, k * l * MLDSA_N elements, caller owned.
  • aLen Number of sword32 elements in a.
  • rho Public seed the matrix was expanded from.
  • rhoLen Length of rho; must be MLDSA_PUB_SEED_SZ.

See:

Return:

  • 0 on success.
  • BAD_FUNC_ARG if a pointer is NULL, rhoLen is not MLDSA_PUB_SEED_SZ, aLen is not k * l * MLDSA_N, or no public key has been imported yet.
  • PUBLIC_KEY_E if rho does not match the imported public key.

Note: A is derived from the public key and must be integrity-protected exactly as the public key is. An attacker able to substitute it can influence verification. In a secure-boot design the key already lives in protected flash, so store the two together.

The matrix is borrowed, never copied and never freed: it must stay valid and unchanged for as long as the key uses it. It holds k * l * MLDSA_N sword32 elements (not bytes) in row-major (r, s) order and in the NTT domain, exactly as ExpandA produces them.

Import the public key first: the matrix is bound to it by comparing rho. The binding is re-checked on every verify, so replacing the key or the parameters afterwards simply discards the matrix and falls back to expanding A rather than using a stale one.

Example

wc_MlDsaKey key;
int res = 0;

wc_MlDsaKey_Init(&key, NULL, INVALID_DEVID);
wc_MlDsaKey_SetParams(&key, WC_ML_DSA_87);
wc_MlDsaKey_ImportPubRaw(&key, pub, pubLen);
if (wc_MlDsaKey_SetPrecompA(&key, matrixA, matrixALen, pub,
        MLDSA_PUB_SEED_SZ) != 0) {
    // handle error
}
wc_MlDsaKey_VerifyMu(&key, sig, sigLen, mu, muLen, &res);

function wc_MlDsaKey_Verify

int wc_MlDsaKey_Verify(
    wc_MlDsaKey * key,
    const byte * sig,
    word32 sigLen,
    const byte * msg,
    word32 msgLen,
    int * res
)

Legacy ML-DSA verify API without a context parameter. Only available when wolfSSL is built with WOLFSSL_MLDSA_NO_CTX. New code should use wc_MlDsaKey_VerifyCtx() with ctx=NULL and ctxLen=0.

Parameters:

  • key Pointer to a wc_MlDsaKey with the public key.
  • sig Signature bytes to verify.
  • sigLen Length of sig in bytes.
  • msg Message that was signed.
  • msgLen Length of msg in bytes.
  • res Set to 1 on a valid signature, 0 otherwise.

See:

Return: See wc_MlDsaKey_VerifyCtx().

function wc_MlDsaKey_Size

int wc_MlDsaKey_Size(
    wc_MlDsaKey * key
)

Returns the size in bytes of the encoded private key for the parameter set selected on this key. Equivalent to wc_MlDsaKey_PrivSize() and provided for API compatibility.

Parameters:

  • key Pointer to a wc_MlDsaKey with parameters set.

See:

Return:

  • Encoded private key size in bytes on success (positive value).
  • BAD_FUNC_ARG if key is NULL or no parameter set is selected.

function wc_MlDsaKey_PrivSize

int wc_MlDsaKey_PrivSize(
    wc_MlDsaKey * key
)

Returns the size in bytes of the encoded private key for the parameter set selected on this key.

Parameters:

  • key Pointer to a wc_MlDsaKey with parameters set.

See:

Return:

  • Encoded private key size on success (positive value).
  • BAD_FUNC_ARG if key is NULL or no parameter set is selected.

function wc_MlDsaKey_PubSize

int wc_MlDsaKey_PubSize(
    wc_MlDsaKey * key
)

Returns the size in bytes of the encoded public key for the parameter set selected on this key.

Parameters:

  • key Pointer to a wc_MlDsaKey with parameters set.

See:

Return:

  • Encoded public key size on success (positive value).
  • BAD_FUNC_ARG if key is NULL or no parameter set is selected.

function wc_MlDsaKey_SigSize

int wc_MlDsaKey_SigSize(
    wc_MlDsaKey * key
)

Returns the size in bytes of the signature produced by this key's parameter set.

Parameters:

  • key Pointer to a wc_MlDsaKey with parameters set.

See:

Return:

  • Signature size on success (positive value).
  • BAD_FUNC_ARG if key is NULL or no parameter set is selected.

function wc_MlDsaKey_GetPrivLen

int wc_MlDsaKey_GetPrivLen(
    wc_MlDsaKey * key,
    int * len
)

Writes the encoded private key size into *len. Equivalent information to wc_MlDsaKey_PrivSize() but uses an out-parameter style.

Parameters:

  • key Pointer to a wc_MlDsaKey with parameters set.
  • len Receives the private key size in bytes.

See: wc_MlDsaKey_PrivSize

Return:

  • 0 on success.
  • BAD_FUNC_ARG if key or len is NULL, or no parameter set is selected.

function wc_MlDsaKey_GetPubLen

int wc_MlDsaKey_GetPubLen(
    wc_MlDsaKey * key,
    int * len
)

Writes the encoded public key size into *len. Equivalent information to wc_MlDsaKey_PubSize() but uses an out-parameter style.

Parameters:

  • key Pointer to a wc_MlDsaKey with parameters set.
  • len Receives the public key size in bytes.

See: wc_MlDsaKey_PubSize

Return:

  • 0 on success.
  • BAD_FUNC_ARG if key or len is NULL, or no parameter set is selected.

function wc_MlDsaKey_GetSigLen

int wc_MlDsaKey_GetSigLen(
    wc_MlDsaKey * key,
    int * len
)

Writes the signature size into *len. Equivalent information to wc_MlDsaKey_SigSize() but uses an out-parameter style.

Parameters:

  • key Pointer to a wc_MlDsaKey with parameters set.
  • len Receives the signature size in bytes.

See: wc_MlDsaKey_SigSize

Return:

  • 0 on success.
  • BAD_FUNC_ARG if key or len is NULL, or no parameter set is selected.

function wc_MlDsaKey_CheckKey

int wc_MlDsaKey_CheckKey(
    wc_MlDsaKey * key
)

Self-checks an ML-DSA key by recomputing the public key from the private and comparing against the stored public. Only available when wolfSSL is built with WOLFSSL_MLDSA_CHECK_KEY.

Parameters:

  • key Pointer to a wc_MlDsaKey with both public and private parts populated.

Return:

  • 0 if the key is consistent.
  • BAD_FUNC_ARG if key is NULL.
  • PUBLIC_KEY_E if the recomputed public does not match.

function wc_MlDsaKey_ImportPubRaw

int wc_MlDsaKey_ImportPubRaw(
    wc_MlDsaKey * key,
    const byte * in,
    word32 inLen
)

Imports a raw ML-DSA public key. The parameter set must already be selected on the key. inLen must match the size returned by wc_MlDsaKey_PubSize() for the selected parameter set.

Parameters:

  • key Pointer to a wc_MlDsaKey with parameters set.
  • in Raw public key bytes.
  • inLen Length of in in bytes.

See:

Return:

  • 0 on success.
  • BAD_FUNC_ARG if key or in is NULL.
  • BUFFER_E if inLen does not match the expected public key size.

function wc_MlDsaKey_ImportPrivRaw

int wc_MlDsaKey_ImportPrivRaw(
    wc_MlDsaKey * key,
    const byte * priv,
    word32 privSz
)

Imports a raw ML-DSA private key. The parameter set must already be selected. privSz must match the size returned by wc_MlDsaKey_PrivSize().

Parameters:

  • key Pointer to a wc_MlDsaKey with parameters set.
  • priv Raw private key bytes.
  • privSz Length of priv in bytes.

See:

Return:

  • 0 on success.
  • BAD_FUNC_ARG if key or priv is NULL.
  • BUFFER_E if privSz does not match the expected private key size.

function wc_MlDsaKey_ImportKey

int wc_MlDsaKey_ImportKey(
    wc_MlDsaKey * key,
    const byte * priv,
    word32 privSz,
    const byte * pub,
    word32 pubSz
)

Imports a raw ML-DSA key pair (private and public parts together). The parameter set must already be selected.

Parameters:

  • key Pointer to a wc_MlDsaKey with parameters set.
  • priv Raw private key bytes.
  • privSz Length of priv.
  • pub Raw public key bytes.
  • pubSz Length of pub.

See: wc_MlDsaKey_ExportKey

Return:

  • 0 on success.
  • BAD_FUNC_ARG if any required pointer is NULL.
  • BUFFER_E if privSz or pubSz does not match the expected sizes.

function wc_MlDsaKey_ExportPubRaw

int wc_MlDsaKey_ExportPubRaw(
    wc_MlDsaKey * key,
    byte * out,
    word32 * outLen
)

Exports the raw ML-DSA public key. On entry *outLen is the size of out; on success it is updated to the bytes written.

Parameters:

  • key Pointer to a wc_MlDsaKey with a public key.
  • out Buffer that receives the public key.
  • outLen In: size of out. Out: bytes written.

See: wc_MlDsaKey_ImportPubRaw

Return:

  • 0 on success.
  • BAD_FUNC_ARG if any required pointer is NULL.
  • BUFFER_E if *outLen is smaller than the public key size.

function wc_MlDsaKey_ExportPrivRaw

int wc_MlDsaKey_ExportPrivRaw(
    wc_MlDsaKey * key,
    byte * out,
    word32 * outLen
)

Exports the raw ML-DSA private key. On entry *outLen is the size of out; on success it is updated to the bytes written.

Parameters:

  • key Pointer to a wc_MlDsaKey with a private key.
  • out Buffer that receives the private key.
  • outLen In: size of out. Out: bytes written.

See: wc_MlDsaKey_ImportPrivRaw

Return:

  • 0 on success.
  • BAD_FUNC_ARG if any required pointer is NULL.
  • BUFFER_E if *outLen is smaller than the private key size.

function wc_MlDsaKey_ExportKey

int wc_MlDsaKey_ExportKey(
    wc_MlDsaKey * key,
    byte * priv,
    word32 * privSz,
    byte * pub,
    word32 * pubSz
)

Exports both raw public and private ML-DSA key components in one call.

Parameters:

  • key Pointer to a wc_MlDsaKey with both key parts.
  • priv Buffer that receives the private key.
  • privSz In: size of priv. Out: bytes written.
  • pub Buffer that receives the public key.
  • pubSz In: size of pub. Out: bytes written.

See: wc_MlDsaKey_ImportKey

Return:

  • 0 on success.
  • BAD_FUNC_ARG if any required pointer is NULL.
  • BUFFER_E if either buffer is too small.

function wc_MlDsaKey_PrivateKeyDecode

int wc_MlDsaKey_PrivateKeyDecode(
    wc_MlDsaKey * key,
    const byte * input,
    word32 inSz,
    word32 * inOutIdx
)

Parses an ML-DSA private key from a DER/ASN.1 encoded buffer (PKCS#8 OneAsymmetricKey). The parameter set is inferred from the algorithm identifier in the encoding, so it does NOT need to be set beforehand. On success *inOutIdx is advanced past the consumed bytes.

Parameters:

  • key Pointer to an initialized wc_MlDsaKey.
  • input DER-encoded private key bytes.
  • inSz Length of input in bytes.
  • inOutIdx In: offset into input where decoding starts. Out: offset past the consumed bytes.

See:

Return:

  • 0 on success.
  • BAD_FUNC_ARG if any required pointer is NULL.
  • ASN_PARSE_E on malformed encoding.

Only available when WOLFSSL_MLDSA_NO_ASN1 is not defined.

function wc_MlDsaKey_PublicKeyDecode

int wc_MlDsaKey_PublicKeyDecode(
    wc_MlDsaKey * key,
    const byte * input,
    word32 inSz,
    word32 * inOutIdx
)

Parses an ML-DSA public key from a DER/ASN.1 encoded buffer (SubjectPublicKeyInfo). The parameter set is inferred from the algorithm identifier. On success *inOutIdx is advanced past the consumed bytes.

Parameters:

  • key Pointer to an initialized wc_MlDsaKey.
  • input DER-encoded SPKI bytes.
  • inSz Length of input in bytes.
  • inOutIdx In: offset into input where decoding starts. Out: offset past the consumed bytes.

See: wc_MlDsaKey_PublicKeyToDer

Return:

  • 0 on success.
  • BAD_FUNC_ARG if any required pointer is NULL.
  • ASN_PARSE_E on malformed encoding.

function wc_MlDsaKey_PublicKeyToDer

int wc_MlDsaKey_PublicKeyToDer(
    wc_MlDsaKey * key,
    byte * output,
    word32 inLen,
    int withAlg
)

Encodes an ML-DSA public key to DER. When withAlg is non-zero the output is a full SubjectPublicKeyInfo (with AlgorithmIdentifier); when zero the output is the raw public key bytes.

Parameters:

  • key Pointer to a wc_MlDsaKey with a public key.
  • output Buffer that receives the DER encoding, or NULL to query size.
  • inLen Size of output (ignored when output is NULL).
  • withAlg Non-zero to emit SubjectPublicKeyInfo, zero for the raw public key only.

See:

Return:

  • Size of the encoded DER in bytes on success.
  • BAD_FUNC_ARG if key is NULL or no parameter set is selected.
  • BUFFER_E if output is non-NULL and inLen is smaller than the required size.

Pass NULL as output to query the required buffer size.

function wc_MlDsaKey_KeyToDer

int wc_MlDsaKey_KeyToDer(
    wc_MlDsaKey * key,
    byte * output,
    word32 inLen
)

Encodes an ML-DSA key pair (public + private) to DER as a PKCS#8 OneAsymmetricKey structure. Pass NULL as output to query the required buffer size.

Parameters:

  • key Pointer to a wc_MlDsaKey with the private key.
  • output Buffer that receives the DER encoding, or NULL to query size.
  • inLen Size of output (ignored when output is NULL).

See:

Return:

  • Size of the encoded DER in bytes on success.
  • BAD_FUNC_ARG if key is NULL or no parameter set is selected.
  • MISSING_KEY if the private key has not been set.
  • BUFFER_E if output is non-NULL and inLen is too small.

function wc_MlDsaKey_PrivateKeyToDer

int wc_MlDsaKey_PrivateKeyToDer(
    wc_MlDsaKey * key,
    byte * output,
    word32 inLen
)

Encodes the ML-DSA private key to DER. Per FIPS 204 the private key encoding includes the public component, so this function is currently an alias of wc_MlDsaKey_KeyToDer() kept for API parity with other algorithms.

Parameters:

  • key Pointer to a wc_MlDsaKey with the private key.
  • output Buffer that receives the DER encoding, or NULL to query size.
  • inLen Size of output (ignored when output is NULL).

See:

Return:

Updated on 2026-10-27 at 01:14:33 +0000