ML-DSA digital signature algorithm (FIPS 204). More...

#include <string.h>
#include "lcx_mldsa.h"
#include "cx_mldsa_poly.h"
#include "cx_mldsa_polyvec.h"
#include "cx_mldsa_polymat.h"
#include "cx_mldsa_sample.h"
#include "cx_mldsa_packing.h"
#include "cx_mldsa_rounding.h"
#include "cx_mldsa_util.h"
#include "cx_mldsa_internal.h"
#include "lcx_sha3.h"
#include "lcx_hash.h"
#include "lcx_rng.h"

Include dependency graph for cx_mldsa.c:

Go to the source code of this file.

Classes
struct	MLDSA_prehash_info_s
	DER-encoded OID and expected output length for each pre-hash algorithm. (FIPS 204, Section 5.4) More...

struct	MLDSA_formatted_message_s

struct	MLDSA_sign_stack_workspace_s
	Stack-allocated workspace for MLDSA_internal_sign_core. More...

union	MLDSA_verify_phase_overlay_t
	Phase-overlaid scratch union for MLDSA_internal_verify_core. More...

struct	MLDSA_verify_stack_workspace_s
	Stack-allocated workspace for MLDSA_internal_verify_core. More...

Macros
#define	MLDSA_MAX_SIGN_ATTEMPTS 814U

Typedefs
typedef struct MLDSA_prehash_info_s	MLDSA_prehash_info_t
	DER-encoded OID and expected output length for each pre-hash algorithm. (FIPS 204, Section 5.4)

typedef struct MLDSA_formatted_message_s	MLDSA_formatted_message_t

typedef struct MLDSA_sign_stack_workspace_s	MLDSA_sign_stack_workspace_t
	Stack-allocated workspace for MLDSA_internal_sign_core.

typedef struct MLDSA_verify_stack_workspace_s	MLDSA_verify_stack_workspace_t
	Stack-allocated workspace for MLDSA_internal_verify_core.

Functions
static cx_err_t	mldsa_format_message_pure (MLDSA_formatted_message_t mprime, const uint8_t ctx, size_t ctx_len, const uint8_t *msg, size_t msg_len)
	Formats a pure (non-pre-hashed) message into M' (FIPS 204, Section 5.2).

static cx_err_t	mldsa_format_message_prehash (MLDSA_formatted_message_t mprime, const uint8_t ctx, size_t ctx_len, MLDSA_prehash_t prehash_alg, const uint8_t *ph, size_t ph_len)
	Formats a pre-hashed message into M' for HashML-DSA (FIPS 204, Section 5.4).

static void	mldsa_compute_mu (uint8_t mu[MLDSA_CRHBYTES], const uint8_t tr[MLDSA_TRBYTES], const MLDSA_formatted_message_t *mprime)
	Computes mu = SHAKE256(tr \|\| M', 64) for a formatted message M'.

cx_err_t	MLDSA_internal_sign_core (uint8_t sig, size_t sig_len, size_t sig_actual_len, const MLDSA_formatted_message_t formatted_mprime, const uint8_t precomputed_mu, uint8_t rnd, size_t rnd_len, const uint8_t sk, size_t sk_len, MLDSA_param_t param)
	Core ML-DSA signing routine (FIPS 204, Algorithms 2 & 7).

cx_err_t	MLDSA_internal_verify_core (const uint8_t sig, size_t sig_len, const MLDSA_formatted_message_t formatted_mprime, const uint8_t precomputed_mu, const uint8_t pk, size_t pk_len, MLDSA_param_t param)
	Core ML-DSA verification routine (FIPS 204, Algorithms 3 & 8).

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
static const MLDSA_prehash_info_t	MLDSA_PREHASH_INFO [MLDSA_NUM_PREHASH_ALGS]

Detailed Description

ML-DSA digital signature algorithm (FIPS 204).

Implements the top-level ML-DSA key generation, signing, and verification routines as specified in FIPS 204 Algorithms 1, 2, 3, 4, 5, 6, 7, 8.

Definition in file cx_mldsa.c.

Macro Definition Documentation

◆ MLDSA_MAX_SIGN_ATTEMPTS

#define MLDSA_MAX_SIGN_ATTEMPTS 814U

Maximum number of signing attempts before failing. With the FIPS 204 Appendix C bound (>= 814), probability < 2^{-256}.

Definition at line 54 of file cx_mldsa.c.

Typedef Documentation

◆ MLDSA_formatted_message_t

typedef struct MLDSA_formatted_message_s MLDSA_formatted_message_t

Format structure of M' = 0x01 (1b)|| context_len (1b) || context (255b) || OID || PH_M. (FIPS 204, Section 5.4)

◆ MLDSA_prehash_info_t

typedef struct MLDSA_prehash_info_s MLDSA_prehash_info_t

DER-encoded OID and expected output length for each pre-hash algorithm. (FIPS 204, Section 5.4)

Indexed by MLDSA_prehash_t. All OIDs share the NIST algorithm arc 06 09 60 86 48 01 65 03 04 02 xx.

◆ MLDSA_sign_stack_workspace_t

typedef struct MLDSA_sign_stack_workspace_s MLDSA_sign_stack_workspace_t

Stack-allocated workspace for MLDSA_internal_sign_core.

The signer streams the secret key, the masking vector y and the matrix A one polynomial at a time, so the only full vector kept across a rejection-loop iteration is w.

◆ MLDSA_verify_stack_workspace_t

typedef struct MLDSA_verify_stack_workspace_s MLDSA_verify_stack_workspace_t

Stack-allocated workspace for MLDSA_internal_verify_core.

Groups all large intermediate buffers needed by the verification algorithm so that a single local variable covers the entire workspace.

Function Documentation

◆ mldsa_compute_mu()

static void mldsa_compute_mu	(	uint8_t	mu[MLDSA_CRHBYTES],
		const uint8_t	tr[MLDSA_TRBYTES],
		const MLDSA_formatted_message_t *	mprime
	)

static

Computes mu = SHAKE256(tr || M', 64) for a formatted message M'.

Parameters

[out]	mu	Output buffer (MLDSA_CRHBYTES bytes).
[in]	tr	tr value from secret / public key (MLDSA_TRBYTES bytes).
[in]	mprime	Formatted message M'.

Definition at line 280 of file cx_mldsa.c.

◆ mldsa_format_message_prehash()

static cx_err_t mldsa_format_message_prehash	(	MLDSA_formatted_message_t *	mprime,
		const uint8_t *	ctx,
		size_t	ctx_len,
		MLDSA_prehash_t	prehash_alg,
		const uint8_t *	ph,
		size_t	ph_len
	)

static

Formats a pre-hashed message into M' for HashML-DSA (FIPS 204, Section 5.4).

Builds M' = 0x01 || len(ctx) || ctx || OID(prehash_alg) || PH_M.

Parameters

[out]	mprime	Formatted message structure to populate.
[in]	ctx	Context string (may be NULL if `ctx_len` is 0).
[in]	ctx_len	Context string length in bytes (must be <= 255).
[in]	prehash_alg	Pre-hash algorithm selector.
[in]	ph	Pre-hashed message digest.
[in]	ph_len	Digest length (must match the algorithm's output size).

Returns: CX_OK on success, error code otherwise.

Definition at line 232 of file cx_mldsa.c.

◆ mldsa_format_message_pure()

static cx_err_t mldsa_format_message_pure	(	MLDSA_formatted_message_t *	mprime,
		const uint8_t *	ctx,
		size_t	ctx_len,
		const uint8_t *	msg,
		size_t	msg_len
	)

static

Formats a pure (non-pre-hashed) message into M' (FIPS 204, Section 5.2).

Builds M' = 0x00 || len(ctx) || ctx || msg.

Parameters

[out]	mprime	Formatted message structure to populate.
[in]	ctx	Context string (may be NULL if `ctx_len` is 0).
[in]	ctx_len	Context string length in bytes (must be <= 255).
[in]	msg	Message to sign or verify (may be NULL if `msg_len` is 0).
[in]	msg_len	Message length in bytes.

Returns: CX_OK on success, error code otherwise.

Definition at line 187 of file cx_mldsa.c.

◆ MLDSA_internal_sign_core()

cx_err_t MLDSA_internal_sign_core	(	uint8_t *	sig,
		size_t	sig_len,
		size_t *	sig_actual_len,
		const MLDSA_formatted_message_t *	formatted_mprime,
		const uint8_t *	precomputed_mu,
		uint8_t *	rnd,
		size_t	rnd_len,
		const uint8_t *	sk,
		size_t	sk_len,
		MLDSA_param_t	param
	)

Core ML-DSA signing routine (FIPS 204, Algorithms 2 & 7).

Performs the rejection-sampling signing loop. Accepts either a formatted message formatted_mprime (from which mu is derived) or a pre-computed precomputed_mu; exactly one must be non-NULL.

Parameters

[out]	sig	Signature output buffer.
[in]	sig_len	Size of the signature buffer in bytes.
[out]	sig_actual_len	Actual signature length written on success.
[in]	formatted_mprime	Formatted message M' (NULL when using `precomputed_mu`).
[in]	precomputed_mu	Pre-computed mu (NULL when using `formatted_mprime`).
[in]	rnd	Signing randomness (MLDSA_RNDBYTES), or NULL for deterministic signing.
[in]	rnd_len	Length of `rnd` (must be MLDSA_RNDBYTES or 0 if NULL).
[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 317 of file cx_mldsa.c.

◆ MLDSA_internal_verify_core()

cx_err_t MLDSA_internal_verify_core	(	const uint8_t *	sig,
		size_t	sig_len,
		const MLDSA_formatted_message_t *	formatted_mprime,
		const uint8_t *	precomputed_mu,
		const uint8_t *	pk,
		size_t	pk_len,
		MLDSA_param_t	param
	)

Core ML-DSA verification routine (FIPS 204, Algorithms 3 & 8).

Verifies an ML-DSA signature. Accepts either a formatted message formatted_mprime (from which mu is derived) or a pre-computed precomputed_mu; exactly one must be non-NULL.

Parameters

[in]	sig	Signature to verify.
[in]	sig_len	Signature length in bytes.
[in]	formatted_mprime	Formatted message M' (NULL when using `precomputed_mu`).
[in]	precomputed_mu	Pre-computed mu (NULL when using `formatted_mprime`).
[in]	pk	Public key.
[in]	pk_len	Public key length in bytes.
[in]	param	ML-DSA parameter set selector.

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

Definition at line 577 of file cx_mldsa.c.

◆ 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_PREHASH_INFO

const MLDSA_prehash_info_t MLDSA_PREHASH_INFO[MLDSA_NUM_PREHASH_ALGS]

static

Initial value:

= {
  
    {{0x06, 0x09, 0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x01}, 32U},
 
    {{0x06, 0x09, 0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x03}, 64U},
 
    {{0x06, 0x09, 0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x08}, 32U},
 
    {{0x06, 0x09, 0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x0A}, 64U},
 
    {{0x06, 0x09, 0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x0B}, 32U},
 
    {{0x06, 0x09, 0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x0C}, 64U},
}

Definition at line 155 of file cx_mldsa.c.

Classes

Macros

Typedefs

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ MLDSA_MAX_SIGN_ATTEMPTS

Typedef Documentation

◆ MLDSA_formatted_message_t

◆ MLDSA_prehash_info_t

◆ MLDSA_sign_stack_workspace_t

◆ MLDSA_verify_stack_workspace_t

Function Documentation

◆ mldsa_compute_mu()

◆ mldsa_format_message_prehash()

◆ mldsa_format_message_pure()

◆ MLDSA_internal_sign_core()

◆ MLDSA_internal_verify_core()

◆ MLDSA_keygen()

◆ MLDSA_sign()

◆ MLDSA_sign_prehash()

◆ MLDSA_verify()

◆ MLDSA_verify_prehash()

Variable Documentation

◆ MLDSA_PREHASH_INFO