PQLR
Postquantum Crypto Library by QAPP
Hypericum signature scheme

Typedefs

typedef struct hypericum_st * hypericum_t
 hypericum algorithm instance handle More...
 

Enumerations

enum  hypericum_parameterset_t { hypericum_universal, hypericum_fast_sign, hypericum_small_sign, hypericum_parameterset_last }
 Parameter set. More...
 

Functions

PQLR_API hypericum_t hypericum_new (hypericum_parameterset_t parameterset)
 Creates new hypericum instance with selected parameter set. More...
 
PQLR_API void hypericum_free (hypericum_t hypericum)
 Frees hypericum instance and all corresponding resources. More...
 
PQLR_API hypericum_t hypericum_duplicate (const hypericum_t hypericum)
 Duplicates hypericum context. More...
 
PQLR_API pqlr_t hypericum_to_pqlr (hypericum_t hypericum)
 Casts hypericum instance to pqlr instance. More...
 
PQLR_API size_t hypericum_get_signature_bytes_len (hypericum_t hypericum)
 Obtains signature buffer length in bytes for current hypericum instance. More...
 
PQLR_API size_t hypericum_get_public_key_bytes_len (hypericum_t hypericum)
 Obtains public key buffer length in bytes for current hypericum instance. More...
 
PQLR_API size_t hypericum_get_secret_key_bytes_len (hypericum_t hypericum)
 Obtains secret key buffer length in bytes for current hypericum instance. More...
 
PQLR_API void hypericum_generate_keys (const hypericum_t hypericum, uint8_t *result_sk, uint8_t *result_pk)
 Generates random secret key and public key for given context. More...
 
PQLR_API void hypericum_sign (const hypericum_t hypericum, 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 hypericum_verify (const hypericum_t hypericum, 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 Hypericum algorithm implementation, which is a stateless hash-based signature scheme. The basic idea is to authenticate a huge number of few-time signature (FTS) key pairs using a so-called hypertree. FTS schemes are signature schemes that allow a key pair to produce a small number of signatures, e.g., in the order of ten for our parameter sets. For each new message, a (pseudo)random FTS key pair is chosen to sign the message. Signature consists of FTS signature and corresponding authentication information. The authentication path contains all necessary information for constructing Merkle trees and getting the top of hypertree.

General usage

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

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

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

Example code is listed below:

void use_new(void)
{
// free resources
hypericum_free(hypericum);
}
void use_generate_keys(void)
{
const size_t sk_len = hypericum_get_secret_key_bytes_len(hypericum);
const size_t pk_len = hypericum_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));
hypericum_generate_keys(hypericum, sk, pk);
// free resources
free(pk);
free(sk);
hypericum_free(hypericum);
}
void use_sign(void)
{
const size_t sk_len = hypericum_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 = hypericum_get_signature_bytes_len(hypericum);
uint8_t* sig = (uint8_t*)calloc(sig_len, sizeof(uint8_t));
unsigned char msg[] = "test";
hypericum_sign(hypericum, sk, msg, sizeof(msg), sig, &sig_len);
// free resources
free(sig);
free(sk);
hypericum_free(hypericum);
}
void use_verify(void)
{
const size_t pk_len = hypericum_get_public_key_bytes_len(hypericum);
const size_t sig_len = hypericum_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 = hypericum_verify(hypericum, pk, sig, sig_len, msg, sizeof(msg));
// free resources
free(sig);
free(pk);
hypericum_free(hypericum);
}
int main(void)
{
use_new();
use_generate_keys();
use_sign();
use_verify();
}

Typedef Documentation

◆ hypericum_t

typedef struct hypericum_st* hypericum_t

hypericum algorithm instance handle

Note
It could be casted to pqlr_t instance linked to this handle
See also
hypericum_to_pqlr

Enumeration Type Documentation

◆ hypericum_parameterset_t

Parameter set.

Hypericum can be parametrized with one of predefined parameter sets. Based on parameter set, following algorithm properties are changed:

  • security level (in bits)
  • private key size (in bytes)
  • public key size (in bytes)
  • signature size (in bytes)
  • hash count (number of hash operations performed during message signing)
  • hash count (number of hash operations performed during message verification)

Property values summarized in table below.

Paramset Security level Private key size Public key size Signature size Hash count (sign) Hash count (verify)
Universal 120 128 64 28100 2770880 4440
FastSign 120 128 64 58492 217946 11645
SmallSign 120 128 64 18324 544472693 2350

Computation speed will differ depending on chosen parameter sets due to different count of internal hash operations performed.

Enumerator
hypericum_universal 
hypericum_fast_sign 
hypericum_small_sign 
hypericum_parameterset_last 

Function Documentation

◆ hypericum_duplicate()

PQLR_API hypericum_t hypericum_duplicate ( const hypericum_t  hypericum)

Duplicates hypericum context.

Parameters
hypericumcontext to duplicate
Returns
copy of hypericum
See also
sphinx_plut_t
sphinx_plus_new

◆ hypericum_free()

PQLR_API void hypericum_free ( hypericum_t  hypericum)

Frees hypericum instance and all corresponding resources.

Parameters
hypericuminstance to free
See also
hypericum_t
hypericum_new

◆ hypericum_generate_keys()

PQLR_API void hypericum_generate_keys ( const hypericum_t  hypericum,
uint8_t *  result_sk,
uint8_t *  result_pk 
)

Generates random secret key and public key for given context.

Usage:

const size_t sk_len = hypericum_get_secret_key_bytes_len(hypericum);
const size_t pk_len = hypericum_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));
hypericum_generate_keys(hypericum, sk, pk);
Parameters
hypericumInstance of hypericum created with hypericum_new(). If NULL, the fatal error occurs.
[out]result_skContiguous array to receive secret key, of size hypericum_get_secret_key_bytes_len. If NULL, the fatal error occurs.
[out]result_pkContiguous array to receive public key, of size hypericum_get_public_key_bytes_len. If NULL, the fatal error occurs.
See also
hypericum_get_secret_key_bytes_len
hypericum_get_public_key_bytes_len

◆ hypericum_get_public_key_bytes_len()

PQLR_API size_t hypericum_get_public_key_bytes_len ( hypericum_t  hypericum)

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

Parameters
hypericuminitialized hypericum instance
See also
hypericum_t
hypericum_new
Returns
public key buffer length in bytes

◆ hypericum_get_secret_key_bytes_len()

PQLR_API size_t hypericum_get_secret_key_bytes_len ( hypericum_t  hypericum)

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

Parameters
hypericuminitialized hypericum instance
See also
hypericum_t
hypericum_new
Returns
secret key buffer length in bytes

◆ hypericum_get_signature_bytes_len()

PQLR_API size_t hypericum_get_signature_bytes_len ( hypericum_t  hypericum)

Obtains signature buffer length in bytes for current hypericum instance.

Parameters
hypericuminitialized hypericum instance
See also
hypericum_t
hypericum_new
Returns
signature buffer length in bytes

◆ hypericum_new()

PQLR_API hypericum_t hypericum_new ( hypericum_parameterset_t  parameterset)

Creates new hypericum instance with selected parameter set.

Usage:

Parameters
parametersetParameter set (see hypericum_parameterset_t for available options)
Returns
initialized hypericum instance or NULL if out of memory

◆ hypericum_sign()

PQLR_API void hypericum_sign ( const hypericum_t  hypericum,
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:

const size_t sk_len = hypericum_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 = hypericum_get_signature_bytes_len(hypericum);
uint8_t* sig = (uint8_t*)calloc(sig_len, sizeof(uint8_t));
unsigned char msg[] = "test";
hypericum_sign(hypericum, sk, msg, sizeof(msg), sig, &sig_len);
Parameters
hypericumInstance of hypericum created with hypericum_new(). If NULL, the fatal error occurs.
skSecret key, the contiguous array of size hypericum_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 hypericum_get_signature_bytes_len. If NULL, the fatal error
[out]result_sig_lenThe length of a signature in bytes. occurs.
See also
hypericum_get_signature_bytes_len
hypericum_get_secret_key_bytes_len

◆ hypericum_to_pqlr()

PQLR_API pqlr_t hypericum_to_pqlr ( hypericum_t  hypericum)

Casts hypericum instance to pqlr instance.

Parameters
hypericuminitialized hypericum instance
Note
this pqlr instance will be released by hypericum_free
See also
hypericum_t
pqlr_t
hypericum_free
Returns
operable pqlr instance or NULL if hypericum is NULL

◆ hypericum_verify()

PQLR_API int hypericum_verify ( const hypericum_t  hypericum,
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 size_t pk_len = hypericum_get_public_key_bytes_len(hypericum);
const size_t sig_len = hypericum_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 = hypericum_verify(hypericum, pk, sig, sig_len, msg, sizeof(msg));
Parameters
hypericumContext, initialized with hypericum_new(). If NULL, the fatal error occurs.
pkPublic key, the contiguous array of size hypericum_get_public_key_bytes_len. If NULL, the fatal error occurs.
sigSignature, the contiguous array of size `hypericum_get_signature_bytes_len'. If NULL, the fatal error occurs.
sig_lenThe length of a signature in bytes.
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
hypericum_get_signature_bytes_len
hypericum_get_public_key_bytes_len