ML-DSA signature scheme

Typedefs
typedef struct ml_dsa_st *	ml_dsa_t
	ML-DSA algorithm instance handle. More...

Enumerations
enum	ml_dsa_parameterset_t {   ml_dsa_44 , ml_dsa_65 , ml_dsa_87 , ml_dsa_44_r ,   ml_dsa_65_r , ml_dsa_87_r , ml_dsa_last }
	Possible ml_dsa parameters sets. More...

Functions
PQLR_API ml_dsa_t	ml_dsa_new (ml_dsa_parameterset_t parameterset)
	Creates new ml_dsa instance with selected parameter set. More...
PQLR_API void	ml_dsa_free (ml_dsa_t ml_dsa)
	Frees ml_dsa instance and all corresponding resources. More...
PQLR_API ml_dsa_t	ml_dsa_duplicate (const ml_dsa_t ml_dsa)
	Duplicates context of ml_dsa instance. More...
PQLR_API pqlr_t	ml_dsa_to_pqlr (ml_dsa_t ml_dsa)
	Gets pqlr instance linked to this ml_dsa instance. More...
PQLR_API size_t	ml_dsa_get_public_key_bytes_len (const ml_dsa_t ml_dsa)
	Obtains public key buffer length in bytes for current ml_dsa instance. More...
PQLR_API size_t	ml_dsa_get_secret_key_bytes_len (const ml_dsa_t ml_dsa)
	Obtains secret key buffer length in bytes for current ml_dsa instance. More...
PQLR_API size_t	ml_dsa_get_signature_bytes_len (ml_dsa_t ml_dsa)
	Obtains signature buffer length in bytes for current ml_dsa instance. More...
PQLR_API void	ml_dsa_generate_keys (const ml_dsa_t ml_dsa, uint8_t *result_sk, uint8_t *result_pk)
	Generates random secret key and public key for given context. More...
PQLR_API void	ml_dsa_sign (const ml_dsa_t ml_dsa, const uint8_t *sk, const uint8_t *msg, size_t msg_len, uint8_t *result_sig, size_t *result_sig_len)
	Generates signature for given message according to context and secret key. More...
PQLR_API void	ml_dsa_sign_ex (const ml_dsa_t ml_dsa, const uint8_t *sk, const uint8_t *ctx, size_t ctx_len, const uint8_t *msg, size_t msg_len, uint8_t *result_sig, size_t *result_sig_len)
	Generates signature for given message according to context and secret key. More...
PQLR_API int	ml_dsa_verify (const ml_dsa_t ml_dsa, const uint8_t *pk, const uint8_t *sig, size_t sig_len, const uint8_t *msg, size_t msg_len)
	Verifies that given signature is the signature of given message. More...
PQLR_API int	ml_dsa_verify_ex (const ml_dsa_t ml_dsa, const uint8_t *pk, const uint8_t *sig, size_t sig_len, const uint8_t *ctx, size_t ctx_len, const uint8_t *msg, size_t msg_len)
	Verifies that given signature is the signature of given message (extended version). More...

Detailed Description

This module provides ML-DSA algorithm implementation, whose security is based on the hardness of finding short vectors in lattices.

General usage

At first, initialize algorithm's instance with parameters you want with ml_dsa_new(). After that, you can generate secret and public keys using ml_dsa_generate_keys, or sign your message with ml_dsa_sign, or verify message wasn't changed with ml_dsa_verify. You are able to interact with this algorithm likewise pqlr_t instance (change error handler, source of entropy input, e.t.c) via ml_dsa_to_pqlr() call.

After there are no more need in signature scheme it's resources must be made free by ml_dsa_free.

In order to use any ML-DSA signature scheme functions, add the following include:

#include <pqlr/ml_dsa/ml_dsa.h>

Example code is listed below:

#include <pqlr/ml_dsa/ml_dsa.h>
 
#include <stdlib.h>
 
void use_new(void)
{
    ml_dsa_t ml_dsa = ml_dsa_new(ml_dsa_44);
 
    // free resources
    ml_dsa_free(ml_dsa);
}
 
 
void use_generate_keys(void)
{
    ml_dsa_t ml_dsa = ml_dsa_new(ml_dsa_44);
    const size_t sk_len = ml_dsa_get_secret_key_bytes_len(ml_dsa);
    const size_t pk_len = ml_dsa_get_public_key_bytes_len(ml_dsa);
    uint8_t* sk = (uint8_t*)calloc(sk_len, sizeof(uint8_t));
    uint8_t* pk = (uint8_t*)calloc(pk_len, sizeof(uint8_t));
    ml_dsa_generate_keys(ml_dsa, sk, pk);
 
    // free resources
    free(pk);
    free(sk);
    ml_dsa_free(ml_dsa);
}
 
 
void use_sign(void)
{
    ml_dsa_t ml_dsa = ml_dsa_new(ml_dsa_44);
    const size_t sk_len = ml_dsa_get_secret_key_bytes_len(ml_dsa);
    // get secret key from somewhere
    uint8_t* sk = (uint8_t*)calloc(sk_len, sizeof(uint8_t));
    size_t sig_len = ml_dsa_get_signature_bytes_len(ml_dsa);
    uint8_t* sig = (uint8_t*)calloc(sig_len, sizeof(uint8_t));
    unsigned char msg[] = "test";
    ml_dsa_sign(ml_dsa, sk, msg, sizeof(msg), sig, &sig_len);
 
    // free resources
    free(sig);
    free(sk);
    ml_dsa_free(ml_dsa);
}
 
 
void use_verify(void)
{
    ml_dsa_t ml_dsa = ml_dsa_new(ml_dsa_44);
    const size_t pk_len = ml_dsa_get_public_key_bytes_len(ml_dsa);
    size_t sig_len = ml_dsa_get_signature_bytes_len(ml_dsa);
    // get public key and signature from somewhere
    uint8_t* pk = (uint8_t*)calloc(pk_len, sizeof(uint8_t));
    uint8_t* sig = (uint8_t*)calloc(sig_len, sizeof(uint8_t));
    unsigned char msg[] = "test";
    int res = ml_dsa_verify(ml_dsa, pk, sig, sig_len, msg, sizeof(msg));
 
    // free resources
    free(sig);
    free(pk);
    ml_dsa_free(ml_dsa);
}
 
 
int main()
{
    use_new();
    use_generate_keys();
    use_sign();
    use_verify();
}

Typedef Documentation

ml_dsa_t

typedef struct ml_dsa_st* ml_dsa_t

ML-DSA algorithm instance handle.

Note

pqlr_t instance linked to this handle can be obtained

See also

ml_dsa_to_pqlr

Enumeration Type Documentation

ml_dsa_parameterset_t

enum ml_dsa_parameterset_t

Possible ml_dsa parameters sets.

Enumerator
ml_dsa_44
ml_dsa_65
ml_dsa_87
ml_dsa_44_r
ml_dsa_65_r
ml_dsa_87_r
ml_dsa_last

Function Documentation

ml_dsa_duplicate()

PQLR_API ml_dsa_t ml_dsa_duplicate

(

const ml_dsa_t

ml_dsa

)

Duplicates context of ml_dsa instance.

Parameters

ml_dsa

instance to duplicate

Returns

new instance with a duplicated context

ml_dsa_free()

PQLR_API void ml_dsa_free

(

ml_dsa_t

ml_dsa

)

Frees ml_dsa instance and all corresponding resources.

Parameters

[in]

ml_dsa

instance to free

See also

ml_dsa_t

ml_dsa_new

ml_dsa_generate_keys()

PQLR_API void ml_dsa_generate_keys	(	const ml_dsa_t	ml_dsa,
		uint8_t *	result_sk,
		uint8_t *	result_pk
	)

Generates random secret key and public key for given context.

Usage:

    ml_dsa_t ml_dsa = ml_dsa_new(ml_dsa_44);
    const size_t sk_len = ml_dsa_get_secret_key_bytes_len(ml_dsa);
    const size_t pk_len = ml_dsa_get_public_key_bytes_len(ml_dsa);
    uint8_t* sk = (uint8_t*)calloc(sk_len, sizeof(uint8_t));
    uint8_t* pk = (uint8_t*)calloc(pk_len, sizeof(uint8_t));
    ml_dsa_generate_keys(ml_dsa, sk, pk);

Parameters

[in]	ml_dsa	Instance of ml_dsa created with ml_dsa_new(). If NULL, the fatal error occurs.
[out]	result_sk	Contiguous array to receive secret key, of size ml_dsa_get_secret_key_bytes_len. If NULL, the fatal error occurs.
[out]	result_pk	Contiguous array to receive public key, of size ml_dsa_get_public_key_bytes_len. If NULL, the fatal error occurs.

See also

ml_dsa_new

ml_dsa_get_secret_key_bytes_len

ml_dsa_get_public_key_bytes_len

ml_dsa_get_public_key_bytes_len()

PQLR_API size_t ml_dsa_get_public_key_bytes_len

(

const ml_dsa_t

ml_dsa

)

Obtains public key buffer length in bytes for current ml_dsa instance.

Parameters

[in]

ml_dsa

initialized ml_dsa instance

See also

ml_dsa_t

ml_dsa_new

Returns

public key buffer length in bytes

ml_dsa_get_secret_key_bytes_len()

PQLR_API size_t ml_dsa_get_secret_key_bytes_len

(

const ml_dsa_t

ml_dsa

)

Obtains secret key buffer length in bytes for current ml_dsa instance.

Parameters

[in]

ml_dsa

initialized ml_dsa instance

See also

ml_dsa_t

ml_dsa_new

Returns

secret key buffer length in bytes

ml_dsa_get_signature_bytes_len()

PQLR_API size_t ml_dsa_get_signature_bytes_len

(

ml_dsa_t

ml_dsa

)

Obtains signature buffer length in bytes for current ml_dsa instance.

Parameters

[in]

ml_dsa

initialized ml_dsa instance

See also

ml_dsa_t

ml_dsa_new

Returns

signature buffer length in bytes

ml_dsa_new()

PQLR_API ml_dsa_t ml_dsa_new

(

ml_dsa_parameterset_t

parameterset

)

Creates new ml_dsa instance with selected parameter set.

Usage:

    ml_dsa_t ml_dsa = ml_dsa_new(ml_dsa_44);

Parameters

[in]

parameterset

available set of parameters for ml_dsa algorithm

Returns

initialized ml_dsa instance or NULL if out of memory

ml_dsa_sign()

PQLR_API void ml_dsa_sign	(	const ml_dsa_t	ml_dsa,
		const uint8_t *	sk,
		const uint8_t *	msg,
		size_t	msg_len,
		uint8_t *	result_sig,
		size_t *	result_sig_len
	)

Generates signature for given message according to context and secret key.

Usage:

    ml_dsa_t ml_dsa = ml_dsa_new(ml_dsa_44);
    const size_t sk_len = ml_dsa_get_secret_key_bytes_len(ml_dsa);
    // get secret key from somewhere
    uint8_t* sk = (uint8_t*)calloc(sk_len, sizeof(uint8_t));
    size_t sig_len = ml_dsa_get_signature_bytes_len(ml_dsa);
    uint8_t* sig = (uint8_t*)calloc(sig_len, sizeof(uint8_t));
    unsigned char msg[] = "test";
    ml_dsa_sign(ml_dsa, sk, msg, sizeof(msg), sig, &sig_len);

Parameters

[in]	ml_dsa	Instance of ml_dsa created with ml_dsa_new(). If NULL, the fatal error occurs.
[in]	sk	Secret key, the contiguous array of size ml_dsa_get_secret_key_bytes_len. If NULL, the fatal error occurs.
[in]	msg	Message to generate signature of, the contiguous array. If NULL, the fatal error occurs.
[in]	msg_len	The length of a message in bytes. If 0, the fatal error occurs.
[out]	result_sig	Contiguous array to receive signature, of size ml_dsa_get_signature_bytes_len. If NULL, the fatal error occurs.
[out]	result_sig_len	The result signature size.

See also

ml_dsa_get_secret_key_bytes_len

ml_dsa_get_signature_bytes_len

ml_dsa_sign_ex()

PQLR_API void ml_dsa_sign_ex	(	const ml_dsa_t	ml_dsa,
		const uint8_t *	sk,
		const uint8_t *	ctx,
		size_t	ctx_len,
		const uint8_t *	msg,
		size_t	msg_len,
		uint8_t *	result_sig,
		size_t *	result_sig_len
	)

Generates signature for given message according to context and secret key.

Usage:

    ml_dsa_t ml_dsa = ml_dsa_new(ml_dsa_44);
    const size_t sk_len = ml_dsa_get_secret_key_bytes_len(ml_dsa);
    // get secret key from somewhere
    uint8_t* sk = (uint8_t*)calloc(sk_len, sizeof(uint8_t));
    size_t sig_len = ml_dsa_get_signature_bytes_len(ml_dsa);
    uint8_t* sig = (uint8_t*)calloc(sig_len, sizeof(uint8_t));
    unsigned char msg[] = "test";
    ml_dsa_sign(ml_dsa, sk, msg, sizeof(msg), sig, &sig_len);

Parameters

[in]	ml_dsa	Instance of ml_dsa created with ml_dsa_new(). If NULL, the fatal error occurs.
[in]	sk	Secret key, the contiguous array of size ml_dsa_get_secret_key_bytes_len. If NULL, the fatal error occurs.
[in]	ctx	Context string, the contiguous array. If NULL and ctx_len is not 0, the fatal error occurs.
[in]	ctx_len	The length of a message in bytes. If more than 255, the fatal error occurs.
[in]	msg	Message to generate signature of, the contiguous array. If NULL, the fatal error occurs.
[in]	msg_len	The length of a message in bytes. If 0, the fatal error occurs.
[out]	result_sig	Contiguous array to receive signature, of size ml_dsa_get_signature_bytes_len. If NULL, the fatal error occurs.
[out]	result_sig_len	The result signature size.

See also

ml_dsa_get_secret_key_bytes_len

ml_dsa_get_signature_bytes_len

ml_dsa_sign

ml_dsa_to_pqlr()

PQLR_API pqlr_t ml_dsa_to_pqlr

(

ml_dsa_t

ml_dsa

)

Gets pqlr instance linked to this ml_dsa instance.

Parameters

[in]

ml_dsa

initialized ml_dsa instance

Note

this call leaves ml_dsa instance intact
the returned pqlr instance will be released on call to ml_dsa_free()

See also

ml_dsa_t

pqlr_t

ml_dsa_free

Returns

operable pqlr instance or NULL if ml_dsa is NULL

ml_dsa_verify()

PQLR_API int ml_dsa_verify	(	const ml_dsa_t	ml_dsa,
		const uint8_t *	pk,
		const uint8_t *	sig,
		size_t	sig_len,
		const uint8_t *	msg,
		size_t	msg_len
	)

Verifies that given signature is the signature of given message.

Usage:

    ml_dsa_t ml_dsa = ml_dsa_new(ml_dsa_44);
    const size_t pk_len = ml_dsa_get_public_key_bytes_len(ml_dsa);
    size_t sig_len = ml_dsa_get_signature_bytes_len(ml_dsa);
    // get public key and signature from somewhere
    uint8_t* pk = (uint8_t*)calloc(pk_len, sizeof(uint8_t));
    uint8_t* sig = (uint8_t*)calloc(sig_len, sizeof(uint8_t));
    unsigned char msg[] = "test";
    int res = ml_dsa_verify(ml_dsa, pk, sig, sig_len, msg, sizeof(msg));

Parameters

[in]	ml_dsa	Context, initialized with ml_dsa_new(). If NULL, the fatal error occurs.
[in]	pk	Public key, the contiguous array of size ml_dsa_get_public_key_bytes_len. If NULL, the fatal error occurs.
[in]	sig	Signature, the contiguous array of size ‘ml_dsa_get_signature_bytes_len’. If NULL, the fatal error occurs.
[in]	sig_len	The length of a signature in bytes.
[in]	msg	Message to verify signature of, the contiguous array. If NULL, the fatal error occurs.
[in]	msg_len	The length of a message in bytes. If 0, the fatal error occurs.

Returns

0 if given signature is the signature of given message, otherwise non-zero value.

See also

ml_dsa_get_signature_bytes_len

ml_dsa_get_public_key_bytes_len

ml_dsa_verify_ex()

PQLR_API int ml_dsa_verify_ex	(	const ml_dsa_t	ml_dsa,
		const uint8_t *	pk,
		const uint8_t *	sig,
		size_t	sig_len,
		const uint8_t *	ctx,
		size_t	ctx_len,
		const uint8_t *	msg,
		size_t	msg_len
	)

Verifies that given signature is the signature of given message (extended version).

Usage:

    ml_dsa_t ml_dsa = ml_dsa_new(ml_dsa_44);
    const size_t pk_len = ml_dsa_get_public_key_bytes_len(ml_dsa);
    size_t sig_len = ml_dsa_get_signature_bytes_len(ml_dsa);
    // get public key and signature from somewhere
    uint8_t* pk = (uint8_t*)calloc(pk_len, sizeof(uint8_t));
    uint8_t* sig = (uint8_t*)calloc(sig_len, sizeof(uint8_t));
    unsigned char msg[] = "test";
    int res = ml_dsa_verify(ml_dsa, pk, sig, sig_len, msg, sizeof(msg));

Parameters

[in]	ml_dsa	Context, initialized with ml_dsa_new(). If NULL, the fatal error occurs.
[in]	pk	Public key, the contiguous array of size ml_dsa_get_public_key_bytes_len. If NULL, the fatal error occurs.
[in]	sig	Signature, the contiguous array of size ‘ml_dsa_get_signature_bytes_len’. If NULL, the fatal error occurs.
[in]	sig_len	The length of a signature in bytes.
[in]	ctx	Context string, the contiguous array. If NULL and ctx_len is not 0, the fatal error occurs.
[in]	ctx_len	The length of a message in bytes. If more than 255, the fatal error occurs.
[in]	msg	Message to verify signature of, the contiguous array. If NULL, the fatal error occurs.
[in]	msg_len	The length of a message in bytes. If 0, the fatal error occurs.

Returns

0 if given signature is the signature of given message, otherwise non-zero value.

See also

ml_dsa_get_signature_bytes_len

ml_dsa_get_public_key_bytes_len