SPHINCS+ signature scheme

Typedefs
typedef struct sphincs_plus_st *	sphincs_plus_t
	Sphincs_plus algorithm instance handle. More...

Enumerations
enum	sphincs_plus_parameterset_t {   sphincs_plus_parameterset_256s , sphincs_plus_parameterset_256f , sphincs_plus_parameterset_192s , sphincs_plus_parameterset_192f ,   sphincs_plus_parameterset_128s , sphincs_plus_parameterset_128f , sphincs_plus_parameterset_last }
	Parameter set. More...

Functions
PQLR_API sphincs_plus_t	sphincs_plus_new (sphincs_plus_parameterset_t parameterset)
	Creates new sphincs_plus instance with selected parameter set. More...
PQLR_API void	sphincs_plus_free (sphincs_plus_t sphincs_plus)
	Frees sphincs_plus instance and all corresponding resources. More...
PQLR_API sphincs_plus_t	sphincs_plus_duplicate (const sphincs_plus_t sphincs_plus)
	Duplicates sphincs_plus context. More...
PQLR_API pqlr_t	sphincs_plus_to_pqlr (sphincs_plus_t sphincs_plus)
	Casts sphincs_plus instance to pqlr instance. More...
PQLR_API size_t	sphincs_plus_get_signature_bytes_len (sphincs_plus_t sphincs_plus)
	Obtains signature buffer length in bytes for current sphincs_plus instance. More...
PQLR_API size_t	sphincs_plus_get_public_key_bytes_len (sphincs_plus_t sphincs_plus)
	Obtains public key buffer length in bytes for current sphincs_plus instance. More...
PQLR_API size_t	sphincs_plus_get_secret_key_bytes_len (sphincs_plus_t sphincs_plus)
	Obtains secret key buffer length in bytes for current sphincs_plus instance. More...
PQLR_API void	sphincs_plus_generate_keys (const sphincs_plus_t sphincs_plus, uint8_t *result_sk, uint8_t *result_pk)
	Generates random secret key and public key for given context. More...
PQLR_API void	sphincs_plus_sign (const sphincs_plus_t sphincs_plus, 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	sphincs_plus_verify (const sphincs_plus_t sphincs_plus, 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 SPHINCS+ 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 information is roughly a hypertree signature, i.e. a signature using a certification tree of Merkle tree signatures.

General usage

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

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

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

#include <pqlr/sphincs_plus/sphincs_plus.h>

Example code is listed below:

#include <pqlr/sphincs_plus/sphincs_plus.h>
 
void use_new(void)
{
    sphincs_plus_t sphincs_plus =
        sphincs_plus_new(sphincs_plus_parameterset_256s);
 
    // free resources
    sphincs_plus_free(sphincs_plus);
}
 
 
void use_generate_keys(void)
{
    sphincs_plus_t sphincs_plus =
        sphincs_plus_new(sphincs_plus_parameterset_128f);
    const size_t sk_len = sphincs_plus_get_secret_key_bytes_len(sphincs_plus);
    const size_t pk_len = sphincs_plus_get_public_key_bytes_len(sphincs_plus);
    uint8_t* sk = (uint8_t*)calloc(sk_len, sizeof(uint8_t));
    uint8_t* pk = (uint8_t*)calloc(pk_len, sizeof(uint8_t));
    sphincs_plus_generate_keys(sphincs_plus, sk, pk);
 
    // free resources
    free(pk);
    free(sk);
    sphincs_plus_free(sphincs_plus);
}
 
 
void use_sign(void)
{
    sphincs_plus_t sphincs_plus =
        sphincs_plus_new(sphincs_plus_parameterset_128f);
    const size_t sk_len = sphincs_plus_get_secret_key_bytes_len(sphincs_plus);
    // get secret key from somewhere
    uint8_t* sk = (uint8_t*)calloc(sk_len, sizeof(uint8_t));
    size_t sig_len = sphincs_plus_get_signature_bytes_len(sphincs_plus);
    uint8_t* sig = (uint8_t*)calloc(sig_len, sizeof(uint8_t));
    unsigned char msg[] = "test";
    sphincs_plus_sign(sphincs_plus, sk, msg, sizeof(msg), sig, &sig_len);
 
    // free resources
    free(sig);
    free(sk);
    sphincs_plus_free(sphincs_plus);
}
 
 
void use_verify(void)
{
    sphincs_plus_t sphincs_plus =
        sphincs_plus_new(sphincs_plus_parameterset_128f);
    const size_t pk_len = sphincs_plus_get_public_key_bytes_len(sphincs_plus);
    size_t sig_len = sphincs_plus_get_signature_bytes_len(sphincs_plus);
    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 =
        sphincs_plus_verify(sphincs_plus, pk, sig, sig_len, msg, sizeof(msg));
 
    // free resources
    free(sig);
    free(pk);
    sphincs_plus_free(sphincs_plus);
}
 
 
int main(void)
{
    use_new();
    use_generate_keys();
    use_sign();
    use_verify();
}

Typedef Documentation

sphincs_plus_t

typedef struct sphincs_plus_st* sphincs_plus_t

Sphincs_plus algorithm instance handle.

Note

It could be casted to pqlr_t instance linked to this handle

See also

sphincs_plus_to_pqlr

Enumeration Type Documentation

sphincs_plus_parameterset_t

enum sphincs_plus_parameterset_t

Parameter set.

SPHINCS+ 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)

Property values summarized in table below.

Paramset	Security level	Private key size	Public key size	Signature size	Hash count
128s	133	64	32	8 080	2 205 679
128f	128	64	32	16 976	141 551
192s	196	96	48	17 064	4 532 203
192f	194	96	48	35 664	178 234
256s	255	128	64	29 792	3 418 083
256f	254	128	64	49 216	402 466

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

Enumerator
sphincs_plus_parameterset_256s	Slow 256 bit preset.
sphincs_plus_parameterset_256f	Fast 256 bit preset.
sphincs_plus_parameterset_192s	Slow 192 bit preset.
sphincs_plus_parameterset_192f	Fast 192 bit preset.
sphincs_plus_parameterset_128s	Slow 128 bit preset.
sphincs_plus_parameterset_128f	Fast 128 bit preset.
sphincs_plus_parameterset_last

Function Documentation

sphincs_plus_duplicate()

PQLR_API sphincs_plus_t sphincs_plus_duplicate

(

const sphincs_plus_t

sphincs_plus

)

Duplicates sphincs_plus context.

Parameters

sphincs_plus

context to duplicate

Returns

copy of sphincs_plus

See also

sphinx_plut_t

sphinx_plus_new

sphincs_plus_free()

PQLR_API void sphincs_plus_free

(

sphincs_plus_t

sphincs_plus

)

Frees sphincs_plus instance and all corresponding resources.

Parameters

sphincs_plus

instance to free

See also

sphincs_plus_t

sphincs_plus_new

sphincs_plus_generate_keys()

PQLR_API void sphincs_plus_generate_keys	(	const sphincs_plus_t	sphincs_plus,
		uint8_t *	result_sk,
		uint8_t *	result_pk
	)

Generates random secret key and public key for given context.

Usage:

    sphincs_plus_t sphincs_plus =
        sphincs_plus_new(sphincs_plus_parameterset_128f);
    const size_t sk_len = sphincs_plus_get_secret_key_bytes_len(sphincs_plus);
    const size_t pk_len = sphincs_plus_get_public_key_bytes_len(sphincs_plus);
    uint8_t* sk = (uint8_t*)calloc(sk_len, sizeof(uint8_t));
    uint8_t* pk = (uint8_t*)calloc(pk_len, sizeof(uint8_t));
    sphincs_plus_generate_keys(sphincs_plus, sk, pk);

Parameters

	sphincs_plus	Instance of sphincs_plus created with sphincs_plus_new(). If NULL, the fatal error occurs.
[out]	result_sk	Contiguous array to receive secret key, of size sphincs_plus_get_secret_key_bytes_len. If NULL, the fatal error occurs.
[out]	result_pk	Contiguous array to receive public key, of size sphincs_plus_get_public_key_bytes_len. If NULL, the fatal error occurs.

See also

sphincs_plus_get_secret_key_bytes_len

sphincs_plus_get_public_key_bytes_len

sphincs_plus_get_public_key_bytes_len()

PQLR_API size_t sphincs_plus_get_public_key_bytes_len

(

sphincs_plus_t

sphincs_plus

)

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

Parameters

sphincs_plus

initialized sphincs_plus instance

See also

sphincs_plus_t

sphincs_plus_new

Returns

public key buffer length in bytes

sphincs_plus_get_secret_key_bytes_len()

PQLR_API size_t sphincs_plus_get_secret_key_bytes_len

(

sphincs_plus_t

sphincs_plus

)

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

Parameters

sphincs_plus

initialized sphincs_plus instance

See also

sphincs_plus_t

sphincs_plus_new

Returns

secret key buffer length in bytes

sphincs_plus_get_signature_bytes_len()

PQLR_API size_t sphincs_plus_get_signature_bytes_len

(

sphincs_plus_t

sphincs_plus

)

Obtains signature buffer length in bytes for current sphincs_plus instance.

Parameters

sphincs_plus

initialized sphincs_plus instance

See also

sphincs_plus_t

sphincs_plus_new

Returns

signature buffer length in bytes

sphincs_plus_new()

PQLR_API sphincs_plus_t sphincs_plus_new

(

sphincs_plus_parameterset_t

parameterset

)

Creates new sphincs_plus instance with selected parameter set.

Usage:

    sphincs_plus_t sphincs_plus =
        sphincs_plus_new(sphincs_plus_parameterset_256s);

Parameters

parameterset

Parameter set (see sphincs_plus_parameterset_t for available options)

Returns

initialized sphincs_plus instance or NULL if out of memory

sphincs_plus_sign()

PQLR_API void sphincs_plus_sign	(	const sphincs_plus_t	sphincs_plus,
		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:

    sphincs_plus_t sphincs_plus =
        sphincs_plus_new(sphincs_plus_parameterset_128f);
    const size_t sk_len = sphincs_plus_get_secret_key_bytes_len(sphincs_plus);
    // get secret key from somewhere
    uint8_t* sk = (uint8_t*)calloc(sk_len, sizeof(uint8_t));
    size_t sig_len = sphincs_plus_get_signature_bytes_len(sphincs_plus);
    uint8_t* sig = (uint8_t*)calloc(sig_len, sizeof(uint8_t));
    unsigned char msg[] = "test";
    sphincs_plus_sign(sphincs_plus, sk, msg, sizeof(msg), sig, &sig_len);

Parameters

	sphincs_plus	Instance of sphincs_plus created with sphincs_plus_new(). If NULL, the fatal error occurs.
	sk	Secret key, the contiguous array of size sphincs_plus_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 sphincs_plus_get_signature_bytes_len. If NULL, the fatal error occurs.
[out]	result_sig_len	The length of a signature in bytes. If NULL, the fatal error occurs.

See also

sphincs_plus_get_signature_bytes_len

sphincs_plus_get_secret_key_bytes_len

sphincs_plus_to_pqlr()

PQLR_API pqlr_t sphincs_plus_to_pqlr

(

sphincs_plus_t

sphincs_plus

)

Casts sphincs_plus instance to pqlr instance.

Parameters

sphincs_plus

initialized sphincs_plus instance

Note

this pqlr instance will be released by sphincs_plus_free

See also

sphincs_plus_t

pqlr_t

sphincs_plus_free

Returns

operable pqlr instance or NULL if sphincs_plus is NULL

sphincs_plus_verify()

PQLR_API int sphincs_plus_verify	(	const sphincs_plus_t	sphincs_plus,
		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:

    sphincs_plus_t sphincs_plus =
        sphincs_plus_new(sphincs_plus_parameterset_128f);
    const size_t pk_len = sphincs_plus_get_public_key_bytes_len(sphincs_plus);
    size_t sig_len = sphincs_plus_get_signature_bytes_len(sphincs_plus);
    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 =
        sphincs_plus_verify(sphincs_plus, pk, sig, sig_len, msg, sizeof(msg));

Parameters

sphincs_plus	Context, initialized with sphincs_plus_new(). If NULL, the fatal error occurs.
pk	Public key, the contiguous array of size sphincs_plus_get_public_key_bytes_len. If NULL, the fatal error occurs.
sig	Signature, the contiguous array of size ‘sphincs_plus_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

sphincs_plus_get_signature_bytes_len

sphincs_plus_get_public_key_bytes_len