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:

#include <pqlr/hypericum/hypericum.h>
#include <pqlr/hypericum/params.h>

Example code is listed below:

#include <pqlr/hypericum/hypericum.h>
#include <pqlr/hypericum/params.h>
 
void use_new(void)
{
    hypericum_t hypericum = hypericum_new(hypericum_universal);
 
    // free resources
    hypericum_free(hypericum);
}
 
 
void use_generate_keys(void)
{
    hypericum_t hypericum = hypericum_new(hypericum_universal);
    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)
{
    hypericum_t hypericum = hypericum_new(hypericum_universal);
    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)
{
    hypericum_t hypericum = hypericum_new(hypericum_universal);
    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

enum 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

hypericum

context 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

hypericum

instance 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:

    hypericum_t hypericum = hypericum_new(hypericum_universal);
    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

	hypericum	Instance of hypericum created with hypericum_new(). If NULL, the fatal error occurs.
[out]	result_sk	Contiguous array to receive secret key, of size hypericum_get_secret_key_bytes_len. If NULL, the fatal error occurs.
[out]	result_pk	Contiguous 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

hypericum

initialized 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

hypericum

initialized 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

hypericum

initialized 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:

    hypericum_t hypericum = hypericum_new(hypericum_universal);

Parameters

parameterset

Parameter 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:

    hypericum_t hypericum = hypericum_new(hypericum_universal);
    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

	hypericum	Instance of hypericum created with hypericum_new(). If NULL, the fatal error occurs.
	sk	Secret key, the contiguous array of size hypericum_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 hypericum_get_signature_bytes_len. If NULL, the fatal error
[out]	result_sig_len	The 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

hypericum

initialized 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:

    hypericum_t hypericum = hypericum_new(hypericum_universal);
    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

hypericum	Context, initialized with hypericum_new(). If NULL, the fatal error occurs.
pk	Public key, the contiguous array of size hypericum_get_public_key_bytes_len. If NULL, the fatal error occurs.
sig	Signature, the contiguous array of size ‘hypericum_get_signature_bytes_len’. If NULL, the fatal error occurs.
sig_len	The length of a signature in bytes.
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

hypericum_get_signature_bytes_len

hypericum_get_public_key_bytes_len