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)
	Gets pqlr instance linked to this falcon 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

pqlr_t instance linked to this handle can be obtained

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

)

Gets pqlr instance linked to this falcon instance.

Parameters

falcon

initialized falcon instance

Note

this call leaves falcon instance intact
the returned pqlr instance will be released on call to 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