PQLR
Postquantum Crypto Library by QWall
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
}
 Parameter set. More...
 

Functions

PQLR_API sphincs_plus_t sphincs_plus_new (sphincs_plus_parameterset_t parameterset, hashalgo_t hashalgo)
 Creates new sphincs_plus instance with selected parameter set and hashing algorithm. More...
 
PQLR_API void sphincs_plus_free (sphincs_plus_t sphincs_plus)
 Frees sphincs_plus instance and all corresponding resources. More...
 
PQLR_API pqlr_t sphincs_plus_to_pqlr (sphincs_plus_t sphincs_plus)
 Casts sphincs_plus instance to pqlr instance. More...
 
PQLR_API uint32_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 uint32_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 uint32_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)
 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, 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, entropy source, e.t.c) via sphincs_plus_to_pqlr() call.

It is also may be useful to set entropy source with pqlr_set_entropy_source before any SPHINCS+ signature scheme function calls.

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:

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

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.

Function Documentation

◆ sphincs_plus_free()

PQLR_API void sphincs_plus_free ( sphincs_plus_t  sphincs_plus)

Frees sphincs_plus instance and all corresponding resources.

Parameters
sphincs_plusinstance 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 =
const int sk_len = sphincs_plus_get_secret_key_bytes_len(sphincs_plus);
const int 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_plusInstance of sphincs_plus created with sphincs_plus_new(). If NULL, the fatal error occurs.
[out]result_skContiguous array to receive secret key, of size sphincs_plus_get_secret_key_bytes_len. If NULL, the fatal error occurs.
[out]result_pkContiguous 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 uint32_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_plusinitialized 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 uint32_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_plusinitialized 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 uint32_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_plusinitialized 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,
hashalgo_t  hashalgo 
)

Creates new sphincs_plus instance with selected parameter set and hashing algorithm.

Usage:

Parameters
parametersetParameter set (see sphincs_plus_parameterset_t for available options)
hashalgoHashing algorithm (see hashalgo_t for available options)
Returns
initialized sphincs_plus instance

◆ 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 
)

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 =
const int sk_len = sphincs_plus_get_secret_key_bytes_len(sphincs_plus);
const int sig_len = sphincs_plus_get_signature_bytes_len(sphincs_plus);
uint8_t* sk = (uint8_t*)calloc(sk_len, sizeof(uint8_t));
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);
Parameters
sphincs_plusInstance of sphincs_plus created with sphincs_plus_new(). If NULL, the fatal error occurs.
skSecret key, the contiguous array of size sphincs_plus_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 sphincs_plus_get_signature_bytes_len. 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_plusinitialized 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,
const uint8_t *  msg,
size_t  msg_len 
)

Verifies that given signature is the signature of given message.

Usage:

sphincs_plus_t sphincs_plus =
const int pk_len = sphincs_plus_get_public_key_bytes_len(sphincs_plus);
const int 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, msg, sizeof(msg));
Parameters
sphincs_plusContext, initialized with sphincs_plus_new(). If NULL, the fatal error occurs.
pkPublic key, the contiguous array of size sphincs_plus_get_public_key_bytes_len. If NULL, the fatal error occurs.
sigSignature, the contiguous array of size `sphincs_plus_get_signature_bytes_len'. If NULL, the fatal error occurs.
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
sphincs_plus_get_signature_bytes_len
sphincs_plus_get_public_key_bytes_len