Skip to content

wc_mldsa.h

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

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.

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

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.

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_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 or ctxLen is invalid.
  • 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, or hashAlg is not supported.
  • BUFFER_E if the sig buffer is too small.

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 or muLen is not 64.
  • 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.

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_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:

Source code


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

wc_MlDsaKey* wc_MlDsaKey_New(void* heap, int devId);

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

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

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

int wc_MlDsaKey_SetParams(wc_MlDsaKey* key, byte level);

int wc_MlDsaKey_GetParams(wc_MlDsaKey* key, byte* level);

void wc_MlDsaKey_Free(wc_MlDsaKey* key);

int wc_MlDsaKey_MakeKey(wc_MlDsaKey* key, WC_RNG* rng);

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

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

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);

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

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

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);

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

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

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

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);

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

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

int wc_MlDsaKey_Size(wc_MlDsaKey* key);

int wc_MlDsaKey_PrivSize(wc_MlDsaKey* key);

int wc_MlDsaKey_PubSize(wc_MlDsaKey* key);

int wc_MlDsaKey_SigSize(wc_MlDsaKey* key);

int wc_MlDsaKey_GetPrivLen(wc_MlDsaKey* key, int* len);

int wc_MlDsaKey_GetPubLen(wc_MlDsaKey* key, int* len);

int wc_MlDsaKey_GetSigLen(wc_MlDsaKey* key, int* len);

int wc_MlDsaKey_CheckKey(wc_MlDsaKey* key);

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

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

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

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

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

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

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

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

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

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

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

Updated on 2026-07-16 at 03:12:19 +0000