PQLR  v1.4-86-c274fcf7
Postquantum Crypto Library by QAPP
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 *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.

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

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
srcnon-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
falconinstance 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.

Parameters
falconInstance of falcon created with falcon_new(). If NULL, the fatal error occurs.
[out]result_skContiguous array to receive secret key, of size falcon_get_secret_key_bytes_len. If NULL, the fatal error occurs.
[out]result_pkContiguous 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
falconinitialized 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
falconinitialized 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
falconinitialized 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.

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

Parameters
falconInstance of falcon created with falcon_new(). If NULL, the fatal error occurs.
skSecret key, the contiguous array of size falcon_get_secret_key_bytes_len. If NULL, the fatal error occurs.
msgMessage to generate signature of, the contiguous array. If NULL, the fatal error occurs.
msg_lenThe length of a message in bytes. If 0, the fatal error occurs.
[out]result_sigContiguous array to receive signature, of size sig_len. If NULL, the fatal error occurs.
[out]sig_lenThe 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
falconinitialized 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.

Parameters
falconContext, initialized with falcon_new(). If NULL, the fatal error occurs.
pkPublic key, the contiguous array of size falcon_get_public_key_bytes_len. If NULL, the fatal error occurs.
sigSignature, the contiguous array of size ‘sig_len’. If NULL, the fatal error occurs.
sig_lenSignature size.
msgMessage to verify signature of, the contiguous array. If NULL, the fatal error occurs.
msg_lenThe 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