wc_mlkem.h

Functions

	Name
MlKemKey *	wc_MlKemKey_New(int type, void * heap, int devId) Allocates and initializes a new MlKemKey on the heap. The returned pointer must be released with wc_MlKemKey_Delete().
int	wc_MlKemKey_Delete(MlKemKey * key, MlKemKey ** key_p) Frees and zeros a heap_allocated MlKemKey previously returned by wc_MlKemKey_New(). On success the caller's pointer variable is set to NULL via key_p when key_p is not NULL.
int	wc_MlKemKey_Init(MlKemKey * key, int type, void * heap, int devId) Initializes an MlKemKey object in place. The type parameter selects the ML-KEM variant and must be one of WC_ML_KEM_512, WC_ML_KEM_768 or WC_ML_KEM_1024.
int	wc_MlKemKey_Free(MlKemKey * key) Releases resources held by an MlKemKey. After this call the object must be re_initialized with wc_MlKemKey_Init() before it can be used again. Safe to call with a NULL pointer.
int	wc_MlKemKey_Init_Id(MlKemKey * key, int type, const unsigned char * id, int len, void * heap, int devId) Initializes an MlKemKey with a device_side key identifier. Equivalent to wc_MlKemKey_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_MlKemKey_Init_Label(MlKemKey * key, int type, const char * label, void * heap, int devId) Initializes an MlKemKey with a device_side key label. Equivalent to wc_MlKemKey_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_MlKemKey_MakeKey(MlKemKey * key, WC_RNG * rng) Generates a new ML-KEM key pair using the provided RNG. Both the public and private components are populated on success.
int	wc_MlKemKey_MakeKeyWithRandom(MlKemKey * key, const unsigned char * rand, int len) Deterministic key generation: produces an ML-KEM key pair from the supplied 64 bytes of randomness instead of an RNG. Useful for known-answer tests and for applications that derive key randomness from another secret.
int	wc_MlKemKey_CipherTextSize(MlKemKey * key, word32 * len) Returns the ciphertext size in bytes for the variant selected on this key.
int	wc_MlKemKey_SharedSecretSize(MlKemKey * key, word32 * len) Returns the shared_secret size in bytes for ML_KEM. The value is the same (32 bytes) across all parameter sets but is queried programmatically for symmetry with wc_MlKemKey_CipherTextSize().
int	wc_MlKemKey_Encapsulate(MlKemKey * key, unsigned char * ct, unsigned char * ss, WC_RNG * rng) Encapsulates a fresh shared secret against the public key held in key. Produces a ciphertext that the holder of the corresponding private key can pass to wc_MlKemKey_Decapsulate() to recover the same shared secret.
int	wc_MlKemKey_EncapsulateWithRandom(MlKemKey * key, unsigned char * ct, unsigned char * ss, const unsigned char * rand, int len) Deterministic variant of wc_MlKemKey_Encapsulate(). Uses the supplied 32 bytes of randomness instead of consuming output from an RNG.
int	wc_MlKemKey_Decapsulate(MlKemKey * key, unsigned char * ss, const unsigned char * ct, word32 len) Decapsulates a ciphertext using the private key held in key and recovers the shared secret produced by wc_MlKemKey_Encapsulate(). ML_KEM decapsulation is constant time and includes an implicit_rejection check on malformed ciphertexts (an attacker cannot learn the validity of ct from the runtime).
int	wc_MlKemKey_DecodePrivateKey(MlKemKey * key, const unsigned char * in, word32 len) Decodes a raw ML_KEM private key into key. The variant must already be selected on the key (typically via wc_MlKemKey_Init() or wc_MlKemKey_New()) and len must match the private key size for that variant.
int	wc_MlKemKey_DecodePublicKey(MlKemKey * key, const unsigned char * in, word32 len) Decodes a raw ML-KEM public key into key. The variant must already be selected on the key and len must match the public key size for that variant.
int	wc_MlKemKey_PrivateKeySize(MlKemKey * key, word32 * len) Returns the encoded private key size in bytes for the variant selected on this key.
int	wc_MlKemKey_PublicKeySize(MlKemKey * key, word32 * len) Returns the encoded public key size in bytes for the variant selected on this key.
int	wc_MlKemKey_EncodePrivateKey(MlKemKey * key, unsigned char * out, word32 len) Encodes the ML_KEM private key into out. The out buffer length must be exactly wc_MlKemKey_PrivateKeySize() bytes.
int	wc_MlKemKey_EncodePublicKey(MlKemKey * key, unsigned char * out, word32 len) Encodes the ML_KEM public key into out. The out buffer length must be exactly wc_MlKemKey_PublicKeySize() bytes.

Functions Documentation

function wc_MlKemKey_New

MlKemKey * wc_MlKemKey_New(
    int type,
    void * heap,
    int devId
)

Allocates and initializes a new MlKemKey on the heap. The returned pointer must be released with wc_MlKemKey_Delete().

Parameters:

type ML-KEM variant: WC_ML_KEM_512, WC_ML_KEM_768 or WC_ML_KEM_1024.
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 MlKemKey on success.
NULL on allocation failure or if type is invalid.

ML-KEM (FIPS 203) is a quantum-resistant key encapsulation mechanism. The type parameter selects the variant: WC_ML_KEM_512 (NIST security level 1), WC_ML_KEM_768 (level 3) or WC_ML_KEM_1024 (level 5).

Example

MlKemKey* key = wc_MlKemKey_New(WC_ML_KEM_768, NULL,
    INVALID_DEVID);
if (key == NULL) {
    // allocation failed
}
// ... use key ...
wc_MlKemKey_Delete(key, &key);

function wc_MlKemKey_Delete

int wc_MlKemKey_Delete(
    MlKemKey * key,
    MlKemKey ** key_p
)

Frees and zeros a heap-allocated MlKemKey previously returned by wc_MlKemKey_New(). On success the caller's pointer variable is set to NULL via key_p when key_p is not NULL.

Parameters:

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

See: wc_MlKemKey_New

Return:

0 on success.
BAD_FUNC_ARG if key is NULL.

function wc_MlKemKey_Init

int wc_MlKemKey_Init(
    MlKemKey * key,
    int type,
    void * heap,
    int devId
)

Initializes an MlKemKey object in place. The type parameter selects the ML-KEM variant and must be one of WC_ML_KEM_512, WC_ML_KEM_768 or WC_ML_KEM_1024.

Parameters:

key Pointer to the MlKemKey to initialize.
type ML-KEM variant: WC_ML_KEM_512, WC_ML_KEM_768 or WC_ML_KEM_1024.
heap Heap hint for dynamic memory allocation. May be NULL.
devId Device identifier for hardware crypto callbacks.

See:

Return:

0 on success.
BAD_FUNC_ARG if key is NULL or type is invalid.
NOT_COMPILED_IN if type names a variant that was disabled at build time.

Example

MlKemKey key;
int ret;

ret = wc_MlKemKey_Init(&key, WC_ML_KEM_768, NULL, INVALID_DEVID);
if (ret != 0) {
    // error initializing key
}
// ... use key ...
wc_MlKemKey_Free(&key);

function wc_MlKemKey_Free

int wc_MlKemKey_Free(
    MlKemKey * key
)

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

Parameters:

key Pointer to the MlKemKey to free.

See: wc_MlKemKey_Init

Return: 0 on success, including when key is NULL.

function wc_MlKemKey_Init_Id

int wc_MlKemKey_Init_Id(
    MlKemKey * key,
    int type,
    const unsigned char * id,
    int len,
    void * heap,
    int devId
)

Initializes an MlKemKey with a device-side key identifier. Equivalent to wc_MlKemKey_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 MlKemKey to initialize.
type ML-KEM variant identifier.
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 the range [0, MLKEM_MAX_ID_LEN].
heap Heap hint for dynamic memory allocation.
devId Device identifier for the crypto callback.

See:

Return:

0 on success.
BAD_FUNC_ARG if key is NULL, if id is NULL while len is non-zero, or if type is invalid.
BUFFER_E if len is negative or exceeds MLKEM_MAX_ID_LEN.

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

function wc_MlKemKey_Init_Label

int wc_MlKemKey_Init_Label(
    MlKemKey * key,
    int type,
    const char * label,
    void * heap,
    int devId
)

Initializes an MlKemKey with a device-side key label. Equivalent to wc_MlKemKey_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 MlKemKey to initialize.
type ML-KEM variant identifier.
label NUL-terminated device-side key label.
heap Heap hint for dynamic memory allocation.
devId Device identifier for the crypto callback.

See:

Return:

0 on success.
BAD_FUNC_ARG if key or label is NULL or type is invalid.

function wc_MlKemKey_MakeKey

int wc_MlKemKey_MakeKey(
    MlKemKey * key,
    WC_RNG * rng
)

Generates a new ML-KEM key pair using the provided RNG. Both the public and private components are populated on success.

Parameters:

key Pointer to an initialized MlKemKey.
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

MlKemKey key;
WC_RNG rng;

wc_MlKemKey_Init(&key, WC_ML_KEM_768, NULL, INVALID_DEVID);
wc_InitRng(&rng);

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

function wc_MlKemKey_MakeKeyWithRandom

int wc_MlKemKey_MakeKeyWithRandom(
    MlKemKey * key,
    const unsigned char * rand,
    int len
)

Deterministic key generation: produces an ML-KEM key pair from the supplied 64 bytes of randomness instead of an RNG. Useful for known-answer tests and for applications that derive key randomness from another secret.

Parameters:

key Pointer to an initialized MlKemKey.
rand Pointer to a buffer of randomness.
len Length of rand in bytes; must be 64.

See: wc_MlKemKey_MakeKey

Return:

0 on success.
BAD_FUNC_ARG if any required pointer is NULL or len is not 64.

function wc_MlKemKey_CipherTextSize

int wc_MlKemKey_CipherTextSize(
    MlKemKey * key,
    word32 * len
)

Returns the ciphertext size in bytes for the variant selected on this key.

Parameters:

key Pointer to an initialized MlKemKey.
len Receives the ciphertext size in bytes.

See:

Return:

0 on success.
BAD_FUNC_ARG if key or len is NULL.

function wc_MlKemKey_SharedSecretSize

int wc_MlKemKey_SharedSecretSize(
    MlKemKey * key,
    word32 * len
)

Returns the shared-secret size in bytes for ML-KEM. The value is the same (32 bytes) across all parameter sets but is queried programmatically for symmetry with wc_MlKemKey_CipherTextSize().

Parameters:

key Pointer to an initialized MlKemKey.
len Receives the shared-secret size in bytes.

See: wc_MlKemKey_CipherTextSize

Return:

0 on success.
BAD_FUNC_ARG if key or len is NULL.

function wc_MlKemKey_Encapsulate

int wc_MlKemKey_Encapsulate(
    MlKemKey * key,
    unsigned char * ct,
    unsigned char * ss,
    WC_RNG * rng
)

Encapsulates a fresh shared secret against the public key held in key. Produces a ciphertext that the holder of the corresponding private key can pass to wc_MlKemKey_Decapsulate() to recover the same shared secret.

Parameters:

key Pointer to an MlKemKey containing a public key.
ct Buffer that receives the ciphertext.
ss Buffer that receives the 32-byte shared secret.
rng Pointer to an initialized WC_RNG.

See:

Return:

0 on success.
BAD_FUNC_ARG if any required pointer is NULL.
BAD_STATE_E if the public key has not been set.
NOT_COMPILED_IN if wolfSSL was built with WC_NO_RNG.
MEMORY_E on allocation failure inside the encapsulation routine.

The ct buffer must be at least wc_MlKemKey_CipherTextSize() bytes and ss must be at least wc_MlKemKey_SharedSecretSize() bytes.

Example

MlKemKey key;
unsigned char ct[WC_ML_KEM_768_CIPHER_TEXT_SIZE];
unsigned char ss[WC_ML_KEM_SS_SZ];

// ... key holds the recipient's public key ...
if (wc_MlKemKey_Encapsulate(&key, ct, ss, &rng) != 0) {
    // error during encapsulation
}
// Send ct to the holder of the matching private key.

function wc_MlKemKey_EncapsulateWithRandom

int wc_MlKemKey_EncapsulateWithRandom(
    MlKemKey * key,
    unsigned char * ct,
    unsigned char * ss,
    const unsigned char * rand,
    int len
)

Deterministic variant of wc_MlKemKey_Encapsulate(). Uses the supplied 32 bytes of randomness instead of consuming output from an RNG.

Parameters:

key Pointer to an MlKemKey containing a public key.
ct Buffer that receives the ciphertext.
ss Buffer that receives the 32-byte shared secret.
rand Buffer of randomness.
len Length of rand in bytes; must be 32.

See: wc_MlKemKey_Encapsulate

Return:

0 on success.
BAD_FUNC_ARG if any required pointer is NULL or len is not 32.

function wc_MlKemKey_Decapsulate

int wc_MlKemKey_Decapsulate(
    MlKemKey * key,
    unsigned char * ss,
    const unsigned char * ct,
    word32 len
)

Decapsulates a ciphertext using the private key held in key and recovers the shared secret produced by wc_MlKemKey_Encapsulate(). ML_KEM decapsulation is constant time and includes an implicit_rejection check on malformed ciphertexts (an attacker cannot learn the validity of ct from the runtime).

Parameters:

key Pointer to an MlKemKey with the private key.
ss Buffer that receives the 32-byte shared secret.
ct The ciphertext to decapsulate.
len Length of ct in bytes.

See:

Return:

0 on success (a shared secret was written to ss).
BAD_FUNC_ARG if any required pointer is NULL.
BAD_STATE_E if the private key has not been set.
BUFFER_E if len does not match the expected ciphertext size for the configured ML-KEM variant.
NOT_COMPILED_IN if the key's ML-KEM variant was disabled at build time.
MEMORY_E on allocation failure.

The ss buffer must be at least wc_MlKemKey_SharedSecretSize() bytes and ct must be exactly wc_MlKemKey_CipherTextSize() bytes.

function wc_MlKemKey_DecodePrivateKey

int wc_MlKemKey_DecodePrivateKey(
    MlKemKey * key,
    const unsigned char * in,
    word32 len
)

Decodes a raw ML-KEM private key into key. The variant must already be selected on the key (typically via wc_MlKemKey_Init() or wc_MlKemKey_New()) and len must match the private key size for that variant.

Parameters:

key Pointer to an initialized MlKemKey.
in Raw private key bytes.
len Length of in in bytes.

See:

Return:

0 on success.
BAD_FUNC_ARG if any required pointer is NULL or len does not match the expected size.

function wc_MlKemKey_DecodePublicKey

int wc_MlKemKey_DecodePublicKey(
    MlKemKey * key,
    const unsigned char * in,
    word32 len
)

Decodes a raw ML-KEM public key into key. The variant must already be selected on the key and len must match the public key size for that variant.

Parameters:

key Pointer to an initialized MlKemKey.
in Raw public key bytes.
len Length of in in bytes.

See:

Return:

0 on success.
BAD_FUNC_ARG if any required pointer is NULL or len does not match the expected size.

function wc_MlKemKey_PrivateKeySize

int wc_MlKemKey_PrivateKeySize(
    MlKemKey * key,
    word32 * len
)

Returns the encoded private key size in bytes for the variant selected on this key.

Parameters:

key Pointer to an initialized MlKemKey.
len Receives the private key size in bytes.

See: wc_MlKemKey_PublicKeySize

Return:

0 on success.
BAD_FUNC_ARG if key or len is NULL.

function wc_MlKemKey_PublicKeySize

int wc_MlKemKey_PublicKeySize(
    MlKemKey * key,
    word32 * len
)

Returns the encoded public key size in bytes for the variant selected on this key.

Parameters:

key Pointer to an initialized MlKemKey.
len Receives the public key size in bytes.

See: wc_MlKemKey_PrivateKeySize

Return:

0 on success.
BAD_FUNC_ARG if key or len is NULL.

function wc_MlKemKey_EncodePrivateKey

int wc_MlKemKey_EncodePrivateKey(
    MlKemKey * key,
    unsigned char * out,
    word32 len
)

Encodes the ML-KEM private key into out. The out buffer length must be exactly wc_MlKemKey_PrivateKeySize() bytes.

Parameters:

key Pointer to an MlKemKey with a private key.
out Buffer that receives the encoded private key.
len Length of out in bytes.

See:

Return:

0 on success.
BAD_FUNC_ARG if any required pointer is NULL.
BAD_STATE_E if the private and public keys are not both set on the key object.
BUFFER_E if len does not exactly equal the encoded private key size for the configured ML-KEM variant.
NOT_COMPILED_IN if the key's ML-KEM variant was disabled at build time.

function wc_MlKemKey_EncodePublicKey

int wc_MlKemKey_EncodePublicKey(
    MlKemKey * key,
    unsigned char * out,
    word32 len
)

Encodes the ML-KEM public key into out. The out buffer length must be exactly wc_MlKemKey_PublicKeySize() bytes.

Parameters:

key Pointer to an MlKemKey with a public key.
out Buffer that receives the encoded public key.
len Length of out in bytes.

See:

Return:

0 on success.
BAD_FUNC_ARG if any required pointer is NULL.
BAD_STATE_E if the public key has not been set.
BUFFER_E if len does not exactly equal the encoded public key size for the configured ML-KEM variant.
NOT_COMPILED_IN if the key's ML-KEM variant was disabled at build time.

Source code


MlKemKey* wc_MlKemKey_New(int type, void* heap, int devId);

int wc_MlKemKey_Delete(MlKemKey* key, MlKemKey** key_p);

int wc_MlKemKey_Init(MlKemKey* key, int type, void* heap, int devId);

int wc_MlKemKey_Free(MlKemKey* key);

int wc_MlKemKey_Init_Id(MlKemKey* key, int type, const unsigned char* id,
    int len, void* heap, int devId);

int wc_MlKemKey_Init_Label(MlKemKey* key, int type, const char* label,
    void* heap, int devId);

int wc_MlKemKey_MakeKey(MlKemKey* key, WC_RNG* rng);

int wc_MlKemKey_MakeKeyWithRandom(MlKemKey* key, const unsigned char* rand,
    int len);

int wc_MlKemKey_CipherTextSize(MlKemKey* key, word32* len);

int wc_MlKemKey_SharedSecretSize(MlKemKey* key, word32* len);

int wc_MlKemKey_Encapsulate(MlKemKey* key, unsigned char* ct,
    unsigned char* ss, WC_RNG* rng);

int wc_MlKemKey_EncapsulateWithRandom(MlKemKey* key, unsigned char* ct,
    unsigned char* ss, const unsigned char* rand, int len);

int wc_MlKemKey_Decapsulate(MlKemKey* key, unsigned char* ss,
    const unsigned char* ct, word32 len);

int wc_MlKemKey_DecodePrivateKey(MlKemKey* key, const unsigned char* in,
    word32 len);

int wc_MlKemKey_DecodePublicKey(MlKemKey* key, const unsigned char* in,
    word32 len);

int wc_MlKemKey_PrivateKeySize(MlKemKey* key, word32* len);

int wc_MlKemKey_PublicKeySize(MlKemKey* key, word32* len);

int wc_MlKemKey_EncodePrivateKey(MlKemKey* key, unsigned char* out,
    word32 len);

int wc_MlKemKey_EncodePublicKey(MlKemKey* key, unsigned char* out,
    word32 len);

Updated on 2026-07-17 at 01:11:29 +0000