PQLR  dev-1426-v1.4-474-b578073a
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.

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

Example code is listed below:

#include <stdlib.h>
#include "falcon/params.h"
void use_new()
{
// free resources
falcon_free(falcon);
}
void use_generate_keys()
{
const int sk_len = falcon_get_secret_key_bytes_len(falcon);
const int 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()
{
const int sk_len = falcon_get_secret_key_bytes_len(falcon);
const int 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);
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()
{
const int pk_len = falcon_get_public_key_bytes_len(falcon);
const int sig_len = falcon_get_signature_bytes_len(falcon);
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()
{
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

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.

Usage:

const int sk_len = falcon_get_secret_key_bytes_len(falcon);
const int 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
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.

Usage:

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.

Usage:

const int sk_len = falcon_get_secret_key_bytes_len(falcon);
const int 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);
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);
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.

Usage:

const int pk_len = falcon_get_public_key_bytes_len(falcon);
const int sig_len = falcon_get_signature_bytes_len(falcon);
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
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