ML-DSA (Module-Lattice Digital Signature Algorithm) public API. More...

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

Include dependency graph for lcx_mldsa.h:

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

Classes
struct	MLDSA_param_info_s
	ML-DSA parameter set descriptor holding all derived sizes. More...

Macros
#define	MLDSA_N 256U

#define	MLDSA_Q 8380417

#define	MLDSA_D 13U

#define	MLDSA_SEEDBYTES 32U

#define	MLDSA_CRHBYTES 64U

#define	MLDSA_TRBYTES 64U

#define	MLDSA_RNDBYTES 32U

#define	MLDSA_POLYT1_PACKEDBYTES 320U

#define	MLDSA_POLYT0_PACKEDBYTES 416U

#define	MLDSA44_K 4U

#define	MLDSA44_L 4U

#define	MLDSA44_ETA 2U

#define	MLDSA44_TAU 39U

#define	MLDSA44_BETA 78U

#define	MLDSA44_GAMMA1 (1 << 17)

#define	MLDSA44_GAMMA2 ((MLDSA_Q - 1) / 88)

#define	MLDSA44_OMEGA 80U

#define	MLDSA44_CTILDEBYTES 32U

#define	MLDSA44_POLYETA_PACKEDBYTES 96U

#define	MLDSA44_POLYZ_PACKEDBYTES 576U

#define	MLDSA44_POLYW1_PACKEDBYTES 192U

#define	MLDSA44_POLYVECH_PACKEDBYTES (MLDSA44_OMEGA + MLDSA44_K)

#define	MLDSA44_PUBLICKEYBYTES (MLDSA_SEEDBYTES + MLDSA44_K * MLDSA_POLYT1_PACKEDBYTES)

#define	MLDSA44_SECRETKEYBYTES

#define	MLDSA44_SIGBYTES

#define	MLDSA65_K 6U

#define	MLDSA65_L 5U

#define	MLDSA65_ETA 4U

#define	MLDSA65_TAU 49U

#define	MLDSA65_BETA 196U

#define	MLDSA65_GAMMA1 (1 << 19)

#define	MLDSA65_GAMMA2 ((MLDSA_Q - 1) / 32)

#define	MLDSA65_OMEGA 55U

#define	MLDSA65_CTILDEBYTES 48U

#define	MLDSA65_POLYETA_PACKEDBYTES 128U

#define	MLDSA65_POLYZ_PACKEDBYTES 640U

#define	MLDSA65_POLYW1_PACKEDBYTES 128U

#define	MLDSA65_POLYVECH_PACKEDBYTES (MLDSA65_OMEGA + MLDSA65_K)

#define	MLDSA65_PUBLICKEYBYTES (MLDSA_SEEDBYTES + MLDSA65_K * MLDSA_POLYT1_PACKEDBYTES)

#define	MLDSA65_SECRETKEYBYTES

#define	MLDSA65_SIGBYTES

#define	MLDSA_MAX_K MLDSA65_K

#define	MLDSA_MAX_L MLDSA65_L

#define	MLDSA_NUM_PARAM_SETS 2U

#define	MLDSA_PREHASH_OID_LEN 11U

Typedefs
typedef enum MLDSA_param_e	MLDSA_param_t
	ML-DSA parameter set selector.

typedef struct MLDSA_param_info_s	MLDSA_param_info_t
	ML-DSA parameter set descriptor holding all derived sizes.

typedef enum MLDSA_prehash_e	MLDSA_prehash_t
	Hash algorithm selector for HashML-DSA pre-hash signatures.

Enumerations
enum	MLDSA_param_e { MLDSA_44 = 0 , MLDSA_65 }
	ML-DSA parameter set selector. More...

enum	MLDSA_prehash_e { MLDSA_PREHASH_SHA256 = 0 , MLDSA_PREHASH_SHA512 , MLDSA_PREHASH_SHA3_256 , MLDSA_PREHASH_SHA3_512 , MLDSA_PREHASH_SHAKE128 , MLDSA_PREHASH_SHAKE256 , MLDSA_NUM_PREHASH_ALGS }
	Hash algorithm selector for HashML-DSA pre-hash signatures. More...

Functions
cx_err_t	MLDSA_keygen (uint8_t pk, size_t pk_len, uint8_t sk, size_t sk_len, MLDSA_param_t param)
	Generates an ML-DSA key pair.

cx_err_t	MLDSA_sign (uint8_t sig, size_t sig_len, size_t sig_actual_len, const uint8_t msg, size_t msg_len, const uint8_t ctx, size_t ctx_len, const uint8_t *sk, size_t sk_len, MLDSA_param_t param)
	ML-DSA signature generation.

cx_err_t	MLDSA_verify (const uint8_t sig, size_t sig_len, const uint8_t msg, size_t msg_len, const uint8_t ctx, size_t ctx_len, const uint8_t pk, size_t pk_len, MLDSA_param_t param)
	ML-DSA signature verification.

cx_err_t	MLDSA_sign_prehash (uint8_t sig, size_t sig_len, size_t sig_actual_len, const uint8_t ph, size_t ph_len, const uint8_t ctx, size_t ctx_len, const uint8_t *sk, size_t sk_len, MLDSA_prehash_t prehash_alg, MLDSA_param_t param)
	HashML-DSA pre-hash signature generation (FIPS 204, Algorithm 4).

cx_err_t	MLDSA_verify_prehash (const uint8_t sig, size_t sig_len, const uint8_t ph, size_t ph_len, const uint8_t ctx, size_t ctx_len, const uint8_t pk, size_t pk_len, MLDSA_prehash_t prehash_alg, MLDSA_param_t param)
	HashML-DSA pre-hash signature verification (FIPS 204, Algorithm 5).

Variables
const MLDSA_param_info_t	MLDSA_PARAM [MLDSA_NUM_PARAM_SETS]
	Lookup table of ML-DSA parameter sets indexed by MLDSA_param_t.

Detailed Description

ML-DSA (Module-Lattice Digital Signature Algorithm) public API.

Provides the public constants, parameter structures, and function prototypes for ML-DSA-44, ML-DSA-65, and ML-DSA-87 as specified in FIPS 204.

ML-DSA-87 support requires the HAVE_MLDSA_87 compilation flag.

Definition in file lcx_mldsa.h.

Macro Definition Documentation

◆ MLDSA_MAX_K

#define MLDSA_MAX_K MLDSA65_K

Maximum k.

Definition at line 160 of file lcx_mldsa.h.

◆ MLDSA_MAX_L

#define MLDSA_MAX_L MLDSA65_L

Maximum l.

Definition at line 161 of file lcx_mldsa.h.

◆ MLDSA_NUM_PARAM_SETS

#define MLDSA_NUM_PARAM_SETS 2U

Number of supported parameter sets.

Definition at line 162 of file lcx_mldsa.h.

Typedef Documentation

◆ MLDSA_param_info_t

typedef struct MLDSA_param_info_s MLDSA_param_info_t

ML-DSA parameter set descriptor holding all derived sizes.

◆ MLDSA_param_t

typedef enum MLDSA_param_e MLDSA_param_t

ML-DSA parameter set selector.

Enumeration Type Documentation

◆ MLDSA_param_e

enum MLDSA_param_e

ML-DSA parameter set selector.

Enumerator
MLDSA_44	ML-DSA-44 (NIST security level 2).
MLDSA_65	ML-DSA-65 (NIST security level 3).

Definition at line 168 of file lcx_mldsa.h.

Function Documentation

◆ MLDSA_keygen()

cx_err_t MLDSA_keygen	(	uint8_t *	pk,
		size_t	pk_len,
		uint8_t *	sk,
		size_t	sk_len,
		MLDSA_param_t	param
	)

Generates an ML-DSA 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-DSA parameter set selector.

Returns: CX_OK on success, error code otherwise.

Definition at line 1258 of file cx_mldsa.c.

◆ MLDSA_sign()

cx_err_t MLDSA_sign	(	uint8_t *	sig,
		size_t	sig_len,
		size_t *	sig_actual_len,
		const uint8_t *	msg,
		size_t	msg_len,
		const uint8_t *	ctx,
		size_t	ctx_len,
		const uint8_t *	sk,
		size_t	sk_len,
		MLDSA_param_t	param
	)

ML-DSA signature generation.

Parameters

[out]	sig	Signature output buffer.
[in]	sig_len	Size of the signature buffer in bytes.
[out]	sig_actual_len	Actual signature length written.
[in]	msg	Message to sign.
[in]	msg_len	Message length in bytes.
[in]	ctx	Context string (may be NULL if ctx_len == 0).
[in]	ctx_len	Context string length (must be <= 255).
[in]	sk	Secret key.
[in]	sk_len	Secret key length in bytes.
[in]	param	ML-DSA parameter set selector.

Returns: CX_OK on success, error code otherwise.

Definition at line 1284 of file cx_mldsa.c.

◆ MLDSA_sign_prehash()

cx_err_t MLDSA_sign_prehash	(	uint8_t *	sig,
		size_t	sig_len,
		size_t *	sig_actual_len,
		const uint8_t *	ph,
		size_t	ph_len,
		const uint8_t *	ctx,
		size_t	ctx_len,
		const uint8_t *	sk,
		size_t	sk_len,
		MLDSA_prehash_t	prehash_alg,
		MLDSA_param_t	param
	)

HashML-DSA pre-hash signature generation (FIPS 204, Algorithm 4).

Signs a pre-hashed message using the HashML-DSA variant. The caller is responsible for hashing the message with the chosen algorithm before calling this function.

Parameters

[out]	sig	Signature output buffer.
[in]	sig_len	Size of the signature buffer in bytes.
[out]	sig_actual_len	Actual signature length written.
[in]	ph	Pre-hashed message digest.
[in]	ph_len	Digest length (must match the hash algorithm).
[in]	ctx	Context string (may be NULL if ctx_len == 0).
[in]	ctx_len	Context string length (must be <= 255).
[in]	sk	Secret key.
[in]	sk_len	Secret key length in bytes.
[in]	prehash_alg	Pre-hash algorithm selector.
[in]	param	ML-DSA parameter set selector.

Returns: CX_OK on success, error code otherwise.

Definition at line 1338 of file cx_mldsa.c.

◆ MLDSA_verify()

cx_err_t MLDSA_verify	(	const uint8_t *	sig,
		size_t	sig_len,
		const uint8_t *	msg,
		size_t	msg_len,
		const uint8_t *	ctx,
		size_t	ctx_len,
		const uint8_t *	pk,
		size_t	pk_len,
		MLDSA_param_t	param
	)

ML-DSA signature verification.

Parameters

[in]	sig	Signature to verify.
[in]	sig_len	Signature length in bytes.
[in]	msg	Message that was signed.
[in]	msg_len	Message length in bytes.
[in]	ctx	Context string (may be NULL if ctx_len == 0).
[in]	ctx_len	Context string length (must be <= 255).
[in]	pk	Public key.
[in]	pk_len	Public key length in bytes.
[in]	param	ML-DSA parameter set selector.

Returns: CX_OK if signature is valid, error code otherwise.

Definition at line 1315 of file cx_mldsa.c.

◆ MLDSA_verify_prehash()

cx_err_t MLDSA_verify_prehash	(	const uint8_t *	sig,
		size_t	sig_len,
		const uint8_t *	ph,
		size_t	ph_len,
		const uint8_t *	ctx,
		size_t	ctx_len,
		const uint8_t *	pk,
		size_t	pk_len,
		MLDSA_prehash_t	prehash_alg,
		MLDSA_param_t	param
	)

HashML-DSA pre-hash signature verification (FIPS 204, Algorithm 5).

Verifies a signature over a pre-hashed message using the HashML-DSA variant. The caller is responsible for hashing the message with the chosen algorithm before calling this function.

Parameters

[in]	sig	Signature to verify.
[in]	sig_len	Signature length in bytes.
[in]	ph	Pre-hashed message digest.
[in]	ph_len	Digest length (must match the hash algorithm).
[in]	ctx	Context string (may be NULL if ctx_len == 0).
[in]	ctx_len	Context string length (must be <= 255).
[in]	pk	Public key.
[in]	pk_len	Public key length in bytes.
[in]	prehash_alg	Pre-hash algorithm selector.
[in]	param	ML-DSA parameter set selector.

Returns: CX_OK if signature is valid, error code otherwise.

Definition at line 1370 of file cx_mldsa.c.

Variable Documentation

◆ MLDSA_PARAM

const MLDSA_param_info_t MLDSA_PARAM[MLDSA_NUM_PARAM_SETS]

extern

Lookup table of ML-DSA parameter sets indexed by MLDSA_param_t.

Definition at line 24 of file cx_mldsa_params.c.

Classes

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ MLDSA_MAX_K

◆ MLDSA_MAX_L

◆ MLDSA_NUM_PARAM_SETS

Typedef Documentation

◆ MLDSA_param_info_t

◆ MLDSA_param_t

Enumeration Type Documentation

◆ MLDSA_param_e

Function Documentation

◆ MLDSA_keygen()

◆ MLDSA_sign()

◆ MLDSA_sign_prehash()

◆ MLDSA_verify()

◆ MLDSA_verify_prehash()

Variable Documentation

◆ MLDSA_PARAM