Dilithium signature scheme

Typedefs
typedef struct dilithium_st *	dilithium_t
	Dilithium algorithm instance handle. More...

Enumerations
enum	dilithium_parameterset_t {   dilithium_2 , dilithium_3 , dilithium_5 , dilithium_2_r ,   dilithium_3_r , dilithium_5_r , dilithium_last }
	Possible dilithium parameters sets. More...

Functions
PQLR_API dilithium_t	dilithium_new (dilithium_parameterset_t parameterset)
	Creates new dilithium instance with selected parameter set. More...
PQLR_API void	dilithium_free (dilithium_t dilithium)
	Frees dilithium instance and all corresponding resources. More...
PQLR_API dilithium_t	dilithium_duplicate (const dilithium_t dilithium)
	Duplicates context of dilithium instance. More...
PQLR_API pqlr_t	dilithium_to_pqlr (dilithium_t dilithium)
	Gets pqlr instance linked to this dilithium instance. More...
PQLR_API size_t	dilithium_get_public_key_bytes_len (const dilithium_t dilithium)
	Obtains public key buffer length in bytes for current dilithium instance. More...
PQLR_API size_t	dilithium_get_secret_key_bytes_len (const dilithium_t dilithium)
	Obtains secret key buffer length in bytes for current dilithium instance. More...
PQLR_API size_t	dilithium_get_signature_bytes_len (dilithium_t dilithium)
	Obtains signature buffer length in bytes for current dilithium instance. More...
PQLR_API void	dilithium_generate_keys (const dilithium_t dilithium, uint8_t *result_sk, uint8_t *result_pk)
	Generates random secret key and public key for given context. More...
PQLR_API void	dilithium_sign (const dilithium_t dilithium, 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 int	dilithium_verify (const dilithium_t dilithium, 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...

Detailed Description

This module provides Dilithium 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 dilithium_new(). After that, you can generate secret and public keys using dilithium_generate_keys, or sign your message with dilithium_sign, or verify message wasn't changed with dilithium_verify. You are able to interact with this algorithm likewise pqlr_t instance (change error handler, source of entropy input, e.t.c) via dilithium_to_pqlr() call.

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

In order to use any Dilithium signature scheme functions, add the following include:

#include <pqlr/dilithium/dilithium.h>

Example code is listed below:

#include <pqlr/dilithium/dilithium.h>
 
#include <stdlib.h>
 
void use_new()
{
    dilithium_t dilithium = dilithium_new(dilithium_2);
 
    // free resources
    dilithium_free(dilithium);
}
 
 
void use_generate_keys()
{
    dilithium_t dilithium = dilithium_new(dilithium_2);
    const size_t sk_len = dilithium_get_secret_key_bytes_len(dilithium);
    const size_t pk_len = dilithium_get_public_key_bytes_len(dilithium);
    uint8_t* sk = (uint8_t*)calloc(sk_len, sizeof(uint8_t));
    uint8_t* pk = (uint8_t*)calloc(pk_len, sizeof(uint8_t));
    dilithium_generate_keys(dilithium, sk, pk);
 
    // free resources
    free(pk);
    free(sk);
    dilithium_free(dilithium);
}
 
 
void use_sign()
{
    dilithium_t dilithium = dilithium_new(dilithium_2);
    const size_t sk_len = dilithium_get_secret_key_bytes_len(dilithium);
    // get secret key from somewhere
    uint8_t* sk = (uint8_t*)calloc(sk_len, sizeof(uint8_t));
    size_t sig_len = dilithium_get_signature_bytes_len(dilithium);
    uint8_t* sig = (uint8_t*)calloc(sig_len, sizeof(uint8_t));
    unsigned char msg[] = "test";
    dilithium_sign(dilithium, sk, msg, sizeof(msg), sig, &sig_len);
 
    // free resources
    free(sig);
    free(sk);
    dilithium_free(dilithium);
}
 
 
void use_verify()
{
    dilithium_t dilithium = dilithium_new(dilithium_2);
    const size_t pk_len = dilithium_get_public_key_bytes_len(dilithium);
    size_t sig_len = dilithium_get_signature_bytes_len(dilithium);
    // 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 = dilithium_verify(dilithium, pk, sig, sig_len, msg, sizeof(msg));
 
    // free resources
    free(sig);
    free(pk);
    dilithium_free(dilithium);
}
 
 
int main()
{
    use_new();
    use_generate_keys();
    use_sign();
    use_verify();
}

Typedef Documentation

dilithium_t

typedef struct dilithium_st* dilithium_t

Dilithium algorithm instance handle.

Note

pqlr_t instance linked to this handle can be obtained

See also

dilithium_to_pqlr

Enumeration Type Documentation

dilithium_parameterset_t

enum dilithium_parameterset_t

Possible dilithium parameters sets.

Enumerator
dilithium_2
dilithium_3
dilithium_5
dilithium_2_r
dilithium_3_r
dilithium_5_r
dilithium_last

Function Documentation

dilithium_duplicate()

PQLR_API dilithium_t dilithium_duplicate

(

const dilithium_t

dilithium

)

Duplicates context of dilithium instance.

Parameters

dilithium

instance to duplicate

Returns

new instance with a duplicated context

dilithium_free()

PQLR_API void dilithium_free

(

dilithium_t

dilithium

)

Frees dilithium instance and all corresponding resources.

Parameters

[in]

dilithium

instance to free

See also

dilithium_t

dilithium_new

dilithium_generate_keys()

PQLR_API void dilithium_generate_keys	(	const dilithium_t	dilithium,
		uint8_t *	result_sk,
		uint8_t *	result_pk
	)

Generates random secret key and public key for given context.

Usage:

    dilithium_t dilithium = dilithium_new(dilithium_2);
    const size_t sk_len = dilithium_get_secret_key_bytes_len(dilithium);
    const size_t pk_len = dilithium_get_public_key_bytes_len(dilithium);
    uint8_t* sk = (uint8_t*)calloc(sk_len, sizeof(uint8_t));
    uint8_t* pk = (uint8_t*)calloc(pk_len, sizeof(uint8_t));
    dilithium_generate_keys(dilithium, sk, pk);

Parameters

[in]	dilithium	Instance of dilithium created with dilithium_new(). If NULL, the fatal error occurs.
[out]	result_sk	Contiguous array to receive secret key, of size dilithium_get_secret_key_bytes_len. If NULL, the fatal error occurs.
[out]	result_pk	Contiguous array to receive public key, of size dilithium_get_public_key_bytes_len. If NULL, the fatal error occurs.

See also

dilithium_new

dilithium_get_secret_key_bytes_len

dilithium_get_public_key_bytes_len

dilithium_get_public_key_bytes_len()

PQLR_API size_t dilithium_get_public_key_bytes_len

(

const dilithium_t

dilithium

)

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

Parameters

[in]

dilithium

initialized dilithium instance

See also

dilithium_t

dilithium_new

Returns

public key buffer length in bytes

dilithium_get_secret_key_bytes_len()

PQLR_API size_t dilithium_get_secret_key_bytes_len

(

const dilithium_t

dilithium

)

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

Parameters

[in]

dilithium

initialized dilithium instance

See also

dilithium_t

dilithium_new

Returns

secret key buffer length in bytes

dilithium_get_signature_bytes_len()

PQLR_API size_t dilithium_get_signature_bytes_len

(

dilithium_t

dilithium

)

Obtains signature buffer length in bytes for current dilithium instance.

Parameters

[in]

dilithium

initialized dilithium instance

See also

dilithium_t

dilithium_new

Returns

signature buffer length in bytes

dilithium_new()

PQLR_API dilithium_t dilithium_new

(

dilithium_parameterset_t

parameterset

)

Creates new dilithium instance with selected parameter set.

Usage:

    dilithium_t dilithium = dilithium_new(dilithium_2);

Parameters

[in]

parameterset

available set of parameters for dilithium algorithm

Returns

initialized dilithium instance or NULL if out of memory

dilithium_sign()

PQLR_API void dilithium_sign	(	const dilithium_t	dilithium,
		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:

    dilithium_t dilithium = dilithium_new(dilithium_2);
    const size_t sk_len = dilithium_get_secret_key_bytes_len(dilithium);
    // get secret key from somewhere
    uint8_t* sk = (uint8_t*)calloc(sk_len, sizeof(uint8_t));
    size_t sig_len = dilithium_get_signature_bytes_len(dilithium);
    uint8_t* sig = (uint8_t*)calloc(sig_len, sizeof(uint8_t));
    unsigned char msg[] = "test";
    dilithium_sign(dilithium, sk, msg, sizeof(msg), sig, &sig_len);

Parameters

[in]	dilithium	Instance of dilithium created with dilithium_new(). If NULL, the fatal error occurs.
[in]	sk	Secret key, the contiguous array of size dilithium_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 dilithium_get_signature_bytes_len. If NULL, the fatal error occurs.
[out]	result_sig_len	The result signature size.

See also

dilithium_get_secret_key_bytes_len

dilithium_get_signature_bytes_len

dilithium_to_pqlr()

PQLR_API pqlr_t dilithium_to_pqlr

(

dilithium_t

dilithium

)

Gets pqlr instance linked to this dilithium instance.

Parameters

[in]

dilithium

initialized dilithium instance

Note

this call leaves dilithium instance intact
the returned pqlr instance will be released on call to dilithium_free()

See also

dilithium_t

pqlr_t

dilithium_free

Returns

operable pqlr instance or NULL if dilithium is NULL

dilithium_verify()

PQLR_API int dilithium_verify	(	const dilithium_t	dilithium,
		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:

    dilithium_t dilithium = dilithium_new(dilithium_2);
    const size_t pk_len = dilithium_get_public_key_bytes_len(dilithium);
    size_t sig_len = dilithium_get_signature_bytes_len(dilithium);
    // 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 = dilithium_verify(dilithium, pk, sig, sig_len, msg, sizeof(msg));

Parameters

[in]	dilithium	Context, initialized with dilithium_new(). If NULL, the fatal error occurs.
[in]	pk	Public key, the contiguous array of size dilithium_get_public_key_bytes_len. If NULL, the fatal error occurs.
[in]	sig	Signature, the contiguous array of size ‘dilithium_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

dilithium_get_signature_bytes_len

dilithium_get_public_key_bytes_len