Falcon signature scheme

Typedefs
typedef struct falcon_st *	falcon_t
	Falcon algorithm instance handle. More...

Enumerations
enum	falcon_parameterset_t { falcon_default , falcon_parameterset_last }
	Parameter set. More...

Functions
PQLR_API falcon_t	falcon_new (falcon_parameterset_t parameterset)
	Creates new falcon instance with selected parameter set. More...
PQLR_API void	falcon_free (falcon_t falcon)
	Frees falcon instance and all corresponding resources. More...
PQLR_API falcon_t	falcon_duplicate (const falcon_t src)
	Duplicates context copying all related resources. More...
PQLR_API pqlr_t	falcon_to_pqlr (falcon_t falcon)
	Casts falcon instance to pqlr instance. More...
PQLR_API size_t	falcon_get_public_key_bytes_len (falcon_t falcon)
	Obtains public key buffer length in bytes for current falcon instance. More...
PQLR_API size_t	falcon_get_secret_key_bytes_len (falcon_t falcon)
	Obtains secret key buffer length in bytes for current falcon instance. More...
PQLR_API size_t	falcon_get_signature_bytes_len (falcon_t falcon)
	Obtains signature buffer length in bytes for current falcon instance. More...
PQLR_API void	falcon_generate_keys (const falcon_t falcon, uint8_t *result_sk, uint8_t *result_pk)
	Generates random secret key and public key for given context. More...
PQLR_API void	falcon_sign (const falcon_t falcon, 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. The signature is non-deterministic, i.e. there are different results for the same message. More...
PQLR_API int	falcon_verify (const falcon_t falcon, 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 Falcon algorithm implementation, which is a stateless hash-based signature scheme.

General usage

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

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

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

#include <pqlr/falcon/falcon.h>

Example code is listed below:

#include <pqlr/falcon/falcon.h>
 
#include <stdlib.h>
#include "falcon/params.h"
 
void use_new(void)
{
    falcon_t falcon = falcon_new(falcon_default);
 
    // free resources
    falcon_free(falcon);
}
 
 
void use_generate_keys(void)
{
    falcon_t falcon = falcon_new(falcon_default);
    const size_t sk_len = falcon_get_secret_key_bytes_len(falcon);
    const size_t pk_len = falcon_get_public_key_bytes_len(falcon);
    uint8_t* sk = (uint8_t*)calloc(sk_len, sizeof(uint8_t));
    uint8_t* pk = (uint8_t*)calloc(pk_len, sizeof(uint8_t));
    falcon_generate_keys(falcon, sk, pk);
 
    // free resources
    free(pk);
    free(sk);
    falcon_free(falcon);
}
 
 
void use_sign(void)
{
    falcon_t falcon = falcon_new(falcon_default);
    const size_t sk_len = falcon_get_secret_key_bytes_len(falcon);
    // get secret key from somewhere
    uint8_t* sk = (uint8_t*)calloc(sk_len, sizeof(uint8_t));
    size_t sig_len = falcon_get_signature_bytes_len(falcon);
    uint8_t* sig = (uint8_t*)calloc(sig_len, sizeof(uint8_t));
    unsigned char msg[] = "test";
    falcon_sign(falcon, sk, msg, sizeof(msg), sig, &sig_len);
 
    // free resources
    free(sig);
    free(sk);
    falcon_free(falcon);
}
 
 
void use_verify(void)
{
    falcon_t falcon = falcon_new(falcon_default);
    const size_t pk_len = falcon_get_public_key_bytes_len(falcon);
    const size_t sig_len = falcon_get_signature_bytes_len(falcon);
    // 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 = falcon_verify(falcon, pk, sig, sig_len, msg, sizeof(msg));
 
    // free resources
    free(sig);
    free(pk);
    falcon_free(falcon);
}
 
 
int main(void)
{
    use_new();
    use_generate_keys();
    use_sign();
    use_verify();
}

Typedef Documentation

falcon_t

typedef struct falcon_st* falcon_t

Falcon algorithm instance handle.

Note

It could be casted to pqlr_t instance linked to this handle

See also

falcon_to_pqlr

Enumeration Type Documentation

falcon_parameterset_t

enum falcon_parameterset_t

Parameter set.

Falcon can be parametrized with one of predefined parameter sets.

Enumerator
falcon_default
falcon_parameterset_last

Function Documentation

falcon_duplicate()

PQLR_API falcon_t falcon_duplicate

(

const falcon_t

src

)

Duplicates context copying all related resources.

Parameters

src	non-null context to duplicate

Returns

falcon instance duplicated from src

See also

falcon_t

falcon_new

falcon_free()

PQLR_API void falcon_free

(

falcon_t

falcon

)

Frees falcon instance and all corresponding resources.

Parameters

falcon

instance to free

See also

falcon_t

falcon_new

falcon_generate_keys()

PQLR_API void falcon_generate_keys	(	const falcon_t	falcon,
		uint8_t *	result_sk,
		uint8_t *	result_pk
	)

Generates random secret key and public key for given context.

Usage:

    falcon_t falcon = falcon_new(falcon_default);
    const size_t sk_len = falcon_get_secret_key_bytes_len(falcon);
    const size_t pk_len = falcon_get_public_key_bytes_len(falcon);
    uint8_t* sk = (uint8_t*)calloc(sk_len, sizeof(uint8_t));
    uint8_t* pk = (uint8_t*)calloc(pk_len, sizeof(uint8_t));
    falcon_generate_keys(falcon, sk, pk);

Parameters

	falcon	Instance of falcon created with falcon_new(). If NULL, the fatal error occurs.
[out]	result_sk	Contiguous array to receive secret key, of size falcon_get_secret_key_bytes_len. If NULL, the fatal error occurs.
[out]	result_pk	Contiguous array to receive public key, of size falcon_get_public_key_bytes_len. If NULL, the fatal error occurs.

See also

falcon_get_secret_key_bytes_len

falcon_get_public_key_bytes_len

falcon_get_public_key_bytes_len()

PQLR_API size_t falcon_get_public_key_bytes_len

(

falcon_t

falcon

)

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

Parameters

falcon

initialized falcon instance

See also

falcon_t

falcon_new

Returns

public key buffer length in bytes

falcon_get_secret_key_bytes_len()

PQLR_API size_t falcon_get_secret_key_bytes_len

(

falcon_t

falcon

)

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

Parameters

falcon

initialized falcon instance

See also

falcon_t

falcon_new

Returns

secret key buffer length in bytes

falcon_get_signature_bytes_len()

PQLR_API size_t falcon_get_signature_bytes_len

(

falcon_t

falcon

)

Obtains signature buffer length in bytes for current falcon instance.

Parameters

falcon

initialized falcon instance

See also

falcon_t

falcon_new

Returns

signature buffer length in bytes

falcon_new()

PQLR_API falcon_t falcon_new

(

falcon_parameterset_t

parameterset

)

Creates new falcon instance with selected parameter set.

Usage:

    falcon_t falcon = falcon_new(falcon_default);

Returns

initialized falcon instance or NULL if out of memory

falcon_sign()

PQLR_API void falcon_sign	(	const falcon_t	falcon,
		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. The signature is non-deterministic, i.e. there are different results for the same message.

Usage:

    falcon_t falcon = falcon_new(falcon_default);
    const size_t sk_len = falcon_get_secret_key_bytes_len(falcon);
    // get secret key from somewhere
    uint8_t* sk = (uint8_t*)calloc(sk_len, sizeof(uint8_t));
    size_t sig_len = falcon_get_signature_bytes_len(falcon);
    uint8_t* sig = (uint8_t*)calloc(sig_len, sizeof(uint8_t));
    unsigned char msg[] = "test";
    falcon_sign(falcon, sk, msg, sizeof(msg), sig, &sig_len);

Note

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

Parameters

	falcon	Instance of falcon created with falcon_new(). If NULL, the fatal error occurs.
	sk	Secret key, the contiguous array of size falcon_get_secret_key_bytes_len. If NULL, the fatal error occurs.
	msg	Message to generate signature of, the contiguous array. If NULL, the fatal error occurs.
	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]	result_sig_len	The result signature size.

See also

falcon_get_secret_key_bytes_len

falcon_to_pqlr()

PQLR_API pqlr_t falcon_to_pqlr

(

falcon_t

falcon

)

Casts falcon instance to pqlr instance.

Parameters

falcon

initialized falcon instance

Note

this pqlr instance will be released by falcon_free

See also

falcon_t

pqlr_t

falcon_free

Returns

operable pqlr instance or NULL if falcon is NULL

falcon_verify()

PQLR_API int falcon_verify	(	const falcon_t	falcon,
		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:

    falcon_t falcon = falcon_new(falcon_default);
    const size_t pk_len = falcon_get_public_key_bytes_len(falcon);
    const size_t sig_len = falcon_get_signature_bytes_len(falcon);
    // 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 = falcon_verify(falcon, pk, sig, sig_len, msg, sizeof(msg));

Parameters

falcon	Context, initialized with falcon_new(). If NULL, the fatal error occurs.
pk	Public key, the contiguous array of size falcon_get_public_key_bytes_len. If NULL, the fatal error occurs.
sig	Signature, the contiguous array of size ‘sig_len’. If NULL, the fatal error occurs.
sig_len	Signature size.
msg	Message to verify signature of, the contiguous array. If NULL, the fatal error occurs.
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

falcon_get_signature_bytes_len

falcon_get_public_key_bytes_len