PQLR common DSA interface

Typedefs
typedef struct pqlr_dsa_st *	pqlr_dsa
	PQLR DSA instance handle. More...

Functions
PQLR_API size_t	pqlr_dsa_num_algs (void)
	Obtains the number of available PQLR DSA algorithms. More...
PQLR_API size_t	pqlr_dsa_get_algs (const char **algs, size_t count)
	Fills the provided buffer with names of available DSA algorithms. More...
PQLR_API pqlr_dsa	pqlr_dsa_new (const pqlr_alg alg)
	Creates new pqlr_dsa instance with selected parameter set. More...
PQLR_API void	pqlr_dsa_free (pqlr_dsa dsa)
	Frees pqlr_dsa instance and all corresponding resources. More...
PQLR_API pqlr_dsa	pqlr_dsa_duplicate (const pqlr_dsa src)
	Duplicates context copying all related resources. More...
PQLR_API size_t	pqlr_dsa_get_public_key_bytes_len (const pqlr_dsa dsa)
	Obtains public key buffer length in bytes for current pqlr_dsa instance. More...
PQLR_API size_t	pqlr_dsa_get_secret_key_bytes_len (const pqlr_dsa dsa)
	Obtains secret key buffer length in bytes for current pqlr_dsa instance. More...
PQLR_API size_t	pqlr_dsa_get_signature_bytes_len (const pqlr_dsa dsa)
	Obtains signature buffer length in bytes for current pqlr_dsa instance. More...
PQLR_API int	pqlr_dsa_keygen (const pqlr_dsa dsa, uint8_t *sk, uint8_t *pk)
	Generates random secret key and public key for given context. More...
PQLR_API int	pqlr_dsa_sign (const pqlr_dsa dsa, const uint8_t *sk, const uint8_t *msg, size_t msg_len, uint8_t *result_sig, size_t *sig_len)
	Generates signature for given message according to context and secret key. More...
PQLR_API int	pqlr_dsa_verify (const pqlr_dsa 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...

Detailed Description

This module provides post-quantum digital signature algorithm implementation.

General usage

At first, initialize algorithm's instance with parameters you want with pqlr_dsa_new(). After that, you can generate secret and public keys using pqlr_dsa_keygen, then sign your message with pqlr_dsa_sign, or verify message wasn't changed with pqlr_dsa_verify.

After the signature scheme is no more needed it's resources must be freed by pqlr_dsa_free.

In order to use any PQLR common DSA interface functions, add following include:

#include <pqlr/common/dsa.h>

Example code is listed below:

#include <pqlr/common/dsa.h>
 
 
void use_dsa_get_algs(void)
{
    size_t nalgs = pqlr_dsa_num_algs();
    const char** dsas = malloc(sizeof(const char*) * nalgs);
    pqlr_dsa_get_algs(dsas, nalgs);
 
    free(dsas);
}
 
 
void use_new(void)
{
    pqlr_alg alg = pqlr_alg_new("hypericum");
    pqlr_dsa hypericum = pqlr_dsa_new(alg);
 
    // free resources
    pqlr_dsa_free(hypericum);
    pqlr_alg_free(alg);
}
 
 
void use_generate_keys(void)
{
    pqlr_alg alg = pqlr_alg_new("hypericum");
    pqlr_dsa hypericum = pqlr_dsa_new(alg);
    const size_t sk_len = pqlr_dsa_get_secret_key_bytes_len(hypericum);
    const size_t pk_len = pqlr_dsa_get_public_key_bytes_len(hypericum);
    uint8_t* sk = (uint8_t*)calloc(sk_len, sizeof(uint8_t));
    uint8_t* pk = (uint8_t*)calloc(pk_len, sizeof(uint8_t));
    pqlr_dsa_keygen(hypericum, sk, pk);
 
    // free resources
    free(pk);
    free(sk);
    pqlr_dsa_free(hypericum);
    pqlr_alg_free(alg);
}
 
 
void use_sign(void)
{
    pqlr_alg alg = pqlr_alg_new("hypericum");
    pqlr_dsa hypericum = pqlr_dsa_new(alg);
    const size_t sk_len = pqlr_dsa_get_secret_key_bytes_len(hypericum);
    // get secret key from somewhere
    uint8_t* sk = (uint8_t*)calloc(sk_len, sizeof(uint8_t));
    size_t sig_len = pqlr_dsa_get_signature_bytes_len(hypericum);
    uint8_t* sig = (uint8_t*)calloc(sig_len, sizeof(uint8_t));
    unsigned char msg[] = "test";
    pqlr_dsa_sign(hypericum, sk, msg, sizeof(msg), sig, &sig_len);
 
    // free resources
    free(sig);
    free(sk);
    pqlr_dsa_free(hypericum);
    pqlr_alg_free(alg);
}
 
 
void use_verify(void)
{
    pqlr_alg alg = pqlr_alg_new("hypericum");
    pqlr_dsa hypericum = pqlr_dsa_new(alg);
    const size_t pk_len = pqlr_dsa_get_public_key_bytes_len(hypericum);
    const size_t sig_len = pqlr_dsa_get_signature_bytes_len(hypericum);
    // 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 = pqlr_dsa_verify(hypericum, pk, sig, sig_len, msg, sizeof(msg));
 
    // free resources
    free(sig);
    free(pk);
    pqlr_dsa_free(hypericum);
    pqlr_alg_free(alg);
}
 
 
int main(void)
{
    use_dsa_get_algs();
    use_new();
    use_generate_keys();
    use_sign();
    use_verify();
}

Typedef Documentation

pqlr_dsa

typedef struct pqlr_dsa_st* pqlr_dsa

PQLR DSA instance handle.

Function Documentation

pqlr_dsa_duplicate()

PQLR_API pqlr_dsa pqlr_dsa_duplicate

(

const pqlr_dsa

src

)

Duplicates context copying all related resources.

Parameters

[in]

src

non-null context to duplicate

Returns

pqlr_dsa instance duplicated from src

See also

pqlr_dsa

pqlr_dsa_new

pqlr_dsa_free()

PQLR_API void pqlr_dsa_free

(

pqlr_dsa

dsa

)

Frees pqlr_dsa instance and all corresponding resources.

Parameters

[in]

dsa

instance to free

See also

pqlr_dsa

pqlr_dsa_new

pqlr_dsa_get_algs()

PQLR_API size_t pqlr_dsa_get_algs	(	const char **	algs,
		size_t	count
	)

Fills the provided buffer with names of available DSA algorithms.

Usage:

    size_t nalgs = pqlr_dsa_num_algs();
    const char** dsas = malloc(sizeof(const char*) * nalgs);
    pqlr_dsa_get_algs(dsas, nalgs);

Note

If the number of DSA algorithms is more than the array size, then it'll be truncated. Individual strings in the output array must not be freed.

Parameters

[out]	algs	Array of DSA names
[in]	count	Array size

Returns

number of algorithms in the output array.

See also

pqlr_alg

pqlr_alg_new

pqlr_dsa_num_algs

pqlr_dsa_get_public_key_bytes_len()

PQLR_API size_t pqlr_dsa_get_public_key_bytes_len

(

const pqlr_dsa

dsa

)

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

Parameters

[in]

dsa

initialized pqlr_dsa instance

See also

pqlr_dsa

pqlr_dsa_new

Returns

public key buffer length in bytes

pqlr_dsa_get_secret_key_bytes_len()

PQLR_API size_t pqlr_dsa_get_secret_key_bytes_len

(

const pqlr_dsa

dsa

)

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

Parameters

[in]

dsa

initialized pqlr_dsa instance

See also

pqlr_dsa

pqlr_dsa_new

Returns

secret key buffer length in bytes

pqlr_dsa_get_signature_bytes_len()

PQLR_API size_t pqlr_dsa_get_signature_bytes_len

(

const pqlr_dsa

dsa

)

Obtains signature buffer length in bytes for current pqlr_dsa instance.

Parameters

[in]

dsa

initialized pqlr_dsa instance

See also

pqlr_dsa

pqlr_dsa_new

Returns

signature buffer length in bytes

pqlr_dsa_keygen()

PQLR_API int pqlr_dsa_keygen	(	const pqlr_dsa	dsa,
		uint8_t *	sk,
		uint8_t *	pk
	)

Generates random secret key and public key for given context.

Usage:

    pqlr_alg alg = pqlr_alg_new("hypericum");
    pqlr_dsa hypericum = pqlr_dsa_new(alg);
    const size_t sk_len = pqlr_dsa_get_secret_key_bytes_len(hypericum);
    const size_t pk_len = pqlr_dsa_get_public_key_bytes_len(hypericum);
    uint8_t* sk = (uint8_t*)calloc(sk_len, sizeof(uint8_t));
    uint8_t* pk = (uint8_t*)calloc(pk_len, sizeof(uint8_t));
    pqlr_dsa_keygen(hypericum, sk, pk);

Parameters

[in]	dsa	Instance of pqlr_dsa created with pqlr_dsa_new(). If NULL, the fatal error occurs.
[out]	sk	Contiguous array to receive secret key, of size pqlr_dsa_get_secret_key_bytes_len. If NULL, the fatal error occurs.
[out]	pk	Contiguous array to receive public key, of size pqlr_dsa_get_public_key_bytes_len. If NULL, the fatal error occurs.

See also

pqlr_dsa_get_secret_key_bytes_len

pqlr_dsa_get_public_key_bytes_len

Returns

0 on success or non-zero value on failure

pqlr_dsa_new()

PQLR_API pqlr_dsa pqlr_dsa_new

(

const pqlr_alg

alg

)

Creates new pqlr_dsa instance with selected parameter set.

Usage:

    pqlr_alg alg = pqlr_alg_new("hypericum");
    pqlr_dsa hypericum = pqlr_dsa_new(alg);

Parameters

[in]

alg

Initialized PQLR DSA algorithm instance

Returns

initialized pqlr_dsa instance or NULL if out of memory

pqlr_dsa_num_algs()

PQLR_API size_t pqlr_dsa_num_algs

(

void

)

Obtains the number of available PQLR DSA algorithms.

Returns

number of algorithms

See also

pqlr_dsa_get_algs

pqlr_alg

pqlr_alg_new

pqlr_dsa_sign()

PQLR_API int pqlr_dsa_sign	(	const pqlr_dsa	dsa,
		const uint8_t *	sk,
		const uint8_t *	msg,
		size_t	msg_len,
		uint8_t *	result_sig,
		size_t *	sig_len
	)

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

Usage:

    pqlr_alg alg = pqlr_alg_new("hypericum");
    pqlr_dsa hypericum = pqlr_dsa_new(alg);
    const size_t sk_len = pqlr_dsa_get_secret_key_bytes_len(hypericum);
    // get secret key from somewhere
    uint8_t* sk = (uint8_t*)calloc(sk_len, sizeof(uint8_t));
    size_t sig_len = pqlr_dsa_get_signature_bytes_len(hypericum);
    uint8_t* sig = (uint8_t*)calloc(sig_len, sizeof(uint8_t));
    unsigned char msg[] = "test";
    pqlr_dsa_sign(hypericum, sk, msg, sizeof(msg), sig, &sig_len);

Note

The maximum length of a signature is given by pqlr_dsa_get_signature_bytes_len, while the actual length may be smaller and is returned in sig_len.

Parameters

[in]	dsa	Instance of pqlr_dsa created with pqlr_dsa_new(). If NULL, the fatal error occurs.
[in]	sk	Secret key, the contiguous array of size pqlr_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 sig_len. If NULL, the fatal error occurs.
[out]	sig_len	The result signature size.

See also

pqlr_dsa_get_secret_key_bytes_len

Returns

0 on success or non-zero value on failure

pqlr_dsa_verify()

PQLR_API int pqlr_dsa_verify	(	const pqlr_dsa	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:

    pqlr_alg alg = pqlr_alg_new("hypericum");
    pqlr_dsa hypericum = pqlr_dsa_new(alg);
    const size_t pk_len = pqlr_dsa_get_public_key_bytes_len(hypericum);
    const size_t sig_len = pqlr_dsa_get_signature_bytes_len(hypericum);
    // 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 = pqlr_dsa_verify(hypericum, pk, sig, sig_len, msg, sizeof(msg));

Parameters

[in]	dsa	Context, initialized with pqlr_dsa_new(). If NULL, the fatal error occurs.
[in]	pk	Public key, the contiguous array of size pqlr_dsa_get_public_key_bytes_len. If NULL, the fatal error occurs.
[in]	sig	Signature, the contiguous array of size ‘sig_len’. If NULL, the fatal error occurs.
[in]	sig_len	Signature size.
[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

pqlr_dsa_get_signature_bytes_len

pqlr_dsa_get_public_key_bytes_len