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_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_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.

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