lcx_mlkem.h File Reference

ML-KEM (Module-Lattice Key Encapsulation Mechanism) public API. More...

#include <stddef.h>
#include <stdint.h>
#include "cx_errors.h"

Include dependency graph for lcx_mlkem.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	MLKEM_param_info_s
	ML-KEM parameter set descriptor holding all derived sizes. More...

Macros
#define	MLKEM_N   256U
#define	MLKEM_Q   3329
#define	MLKEM_Q_HALF   1665
#define	MLKEM_SYMBYTES   32U
#define	MLKEM_SSBYTES   32U
#define	MLKEM_POLYBYTES   384U
#define	MLKEM_POLYCOMPRESSEDBYTES_D10   320U
#define	MLKEM_POLYCOMPRESSEDBYTES_D11   352U
#define	MLKEM_NUM_PARAM_SETS   3U
#define	MLKEM512_K   2U
#define	MLKEM512_ETA1   3U
#define	MLKEM512_ETA2   2U
#define	MLKEM512_DU   10U
#define	MLKEM512_DV   4U
#define	MLKEM512_POLYVECBYTES    (MLKEM512_K * MLKEM_POLYBYTES)
#define	MLKEM512_POLYCOMPRESSEDBYTES_DV   128U
#define	MLKEM512_POLYCOMPRESSEDBYTES_DU   320U
#define	MLKEM512_POLYVECCOMPRESSEDBYTES    (MLKEM512_K * MLKEM512_POLYCOMPRESSEDBYTES_DU)
#define	MLKEM512_INDCPA_PUBLICKEYBYTES    (MLKEM512_POLYVECBYTES + MLKEM_SYMBYTES)
#define	MLKEM512_INDCPA_SECRETKEYBYTES    MLKEM512_POLYVECBYTES
#define	MLKEM512_INDCPA_BYTES
#define	MLKEM512_PUBLICKEYBYTES    MLKEM512_INDCPA_PUBLICKEYBYTES
#define	MLKEM512_SECRETKEYBYTES
#define	MLKEM512_CIPHERTEXTBYTES   MLKEM512_INDCPA_BYTES
#define	MLKEM768_K   3U
#define	MLKEM768_ETA1   2U
#define	MLKEM768_ETA2   2U
#define	MLKEM768_DU   10U
#define	MLKEM768_DV   4U
#define	MLKEM768_POLYVECBYTES    (MLKEM768_K * MLKEM_POLYBYTES)
#define	MLKEM768_POLYCOMPRESSEDBYTES_DV   128U
#define	MLKEM768_POLYCOMPRESSEDBYTES_DU   320U
#define	MLKEM768_POLYVECCOMPRESSEDBYTES    (MLKEM768_K * MLKEM768_POLYCOMPRESSEDBYTES_DU)
#define	MLKEM768_INDCPA_PUBLICKEYBYTES    (MLKEM768_POLYVECBYTES + MLKEM_SYMBYTES)
#define	MLKEM768_INDCPA_SECRETKEYBYTES    MLKEM768_POLYVECBYTES
#define	MLKEM768_INDCPA_BYTES
#define	MLKEM768_PUBLICKEYBYTES    MLKEM768_INDCPA_PUBLICKEYBYTES
#define	MLKEM768_SECRETKEYBYTES
#define	MLKEM768_CIPHERTEXTBYTES   MLKEM768_INDCPA_BYTES
#define	MLKEM1024_K   4U
#define	MLKEM1024_ETA1   2U
#define	MLKEM1024_ETA2   2U
#define	MLKEM1024_DU   11U
#define	MLKEM1024_DV   5U
#define	MLKEM1024_POLYVECBYTES    (MLKEM1024_K * MLKEM_POLYBYTES)
#define	MLKEM1024_POLYCOMPRESSEDBYTES_DV   160U
#define	MLKEM1024_POLYCOMPRESSEDBYTES_DU   352U
#define	MLKEM1024_POLYVECCOMPRESSEDBYTES    (MLKEM1024_K * MLKEM1024_POLYCOMPRESSEDBYTES_DU)
#define	MLKEM1024_INDCPA_PUBLICKEYBYTES    (MLKEM1024_POLYVECBYTES + MLKEM_SYMBYTES)
#define	MLKEM1024_INDCPA_SECRETKEYBYTES    MLKEM1024_POLYVECBYTES
#define	MLKEM1024_INDCPA_BYTES
#define	MLKEM1024_PUBLICKEYBYTES    MLKEM1024_INDCPA_PUBLICKEYBYTES
#define	MLKEM1024_SECRETKEYBYTES
#define	MLKEM1024_CIPHERTEXTBYTES    MLKEM1024_INDCPA_BYTES
#define	MLKEM_MAX_K   MLKEM1024_K

Typedefs
typedef enum MLKEM_param_e	MLKEM_param_t
	ML-KEM parameter set selector.
typedef struct MLKEM_param_info_s	MLKEM_param_info_t
	ML-KEM parameter set descriptor holding all derived sizes.

Enumerations
enum	MLKEM_param_e { MLKEM_512 = 0 , MLKEM_768 , MLKEM_1024 }
	ML-KEM parameter set selector. More...

Functions
cx_err_t	MLKEM_crypto_kem_keypair (uint8_t *pk, size_t pk_len, uint8_t *sk, size_t sk_len, MLKEM_param_t param)
	Generates an ML-KEM key pair.
cx_err_t	MLKEM_crypto_kem_enc (uint8_t *ct, size_t ct_len, uint8_t *ss, size_t ss_len, const uint8_t *pk, size_t pk_len, MLKEM_param_t param)
	ML-KEM encapsulation.
cx_err_t	MLKEM_crypto_kem_dec (uint8_t *ss, size_t ss_len, const uint8_t *ct, size_t ct_len, const uint8_t *sk, size_t sk_len, MLKEM_param_t param)
	ML-KEM decapsulation.

Variables
const MLKEM_param_info_t	MLKEM_PARAM [MLKEM_NUM_PARAM_SETS]
	Lookup table of ML-KEM parameter sets indexed by MLKEM_param_t.

Detailed Description

ML-KEM (Module-Lattice Key Encapsulation Mechanism) public API.

Provides the public constants, parameter structures, and function prototypes for ML-KEM-512, ML-KEM-768, and ML-KEM-1024 as specified in FIPS 203.

Definition in file lcx_mlkem.h.

Macro Definition Documentation

MLKEM_MAX_K

#define MLKEM_MAX_K   MLKEM1024_K

Maximum module rank across all parameter sets.

Definition at line 154 of file lcx_mlkem.h.

Typedef Documentation

MLKEM_param_info_t

typedef struct MLKEM_param_info_s MLKEM_param_info_t

ML-KEM parameter set descriptor holding all derived sizes.

MLKEM_param_t

typedef enum MLKEM_param_e MLKEM_param_t

ML-KEM parameter set selector.

Enumeration Type Documentation

MLKEM_param_e

enum MLKEM_param_e

ML-KEM parameter set selector.

Enumerator
MLKEM_512	ML-KEM-512 (NIST security level 1).
MLKEM_768	ML-KEM-768 (NIST security level 3).
MLKEM_1024	ML-KEM-1024 (NIST security level 5).

Definition at line 159 of file lcx_mlkem.h.

Function Documentation

MLKEM_crypto_kem_dec()

cx_err_t MLKEM_crypto_kem_dec	(	uint8_t *	ss,
		size_t	ss_len,
		const uint8_t *	ct,
		size_t	ct_len,
		const uint8_t *	sk,
		size_t	sk_len,
		MLKEM_param_t	param
	)

ML-KEM decapsulation.

Recovers the shared secret from a ciphertext and a secret key.

Parameters

[out]	ss	Shared secret output buffer.
[in]	ss_len	Size of the shared secret buffer in bytes.
[in]	ct	Ciphertext.
[in]	ct_len	Size of the ciphertext in bytes.
[in]	sk	Secret key.
[in]	sk_len	Size of the secret key in bytes.
[in]	param	ML-KEM parameter set selector.

Returns

CX_OK on success, error code otherwise.

Definition at line 88 of file cx_mlkem.c.

MLKEM_crypto_kem_enc()

cx_err_t MLKEM_crypto_kem_enc	(	uint8_t *	ct,
		size_t	ct_len,
		uint8_t *	ss,
		size_t	ss_len,
		const uint8_t *	pk,
		size_t	pk_len,
		MLKEM_param_t	param
	)

ML-KEM encapsulation.

Produces a ciphertext and a shared secret from a public key using internal randomness.

Parameters

[out]	ct	Ciphertext output buffer.
[in]	ct_len	Size of the ciphertext buffer in bytes.
[out]	ss	Shared secret output buffer.
[in]	ss_len	Size of the shared secret buffer in bytes.
[in]	pk	Public key.
[in]	pk_len	Size of the public key in bytes.
[in]	param	ML-KEM parameter set selector.

Returns

CX_OK on success, error code otherwise.

Definition at line 59 of file cx_mlkem.c.

MLKEM_crypto_kem_keypair()

cx_err_t MLKEM_crypto_kem_keypair	(	uint8_t *	pk,
		size_t	pk_len,
		uint8_t *	sk,
		size_t	sk_len,
		MLKEM_param_t	param
	)

Generates an ML-KEM key pair.

Uses internal randomness to produce the key pair.

Parameters

[out]	pk	Public key output buffer.
[in]	pk_len	Size of the public key buffer in bytes.
[out]	sk	Secret key output buffer.
[in]	sk_len	Size of the secret key buffer in bytes.
[in]	param	ML-KEM parameter set selector.

Returns

CX_OK on success, error code otherwise.

Definition at line 32 of file cx_mlkem.c.

Variable Documentation

MLKEM_PARAM

const MLKEM_param_info_t MLKEM_PARAM[MLKEM_NUM_PARAM_SETS]

extern

Lookup table of ML-KEM parameter sets indexed by MLKEM_param_t.

Definition at line 23 of file cx_mlkem_params.c.