PQLR  dev-1426-v1.4-474-b578073a
Postquantum Crypto Library by QAPP
Rainbow signature scheme

Typedefs

typedef struct rainbow_st * rainbow_t
 Rainbow algorithm instance handle. More...
 

Enumerations

enum  rainbow_parameterset_t { rainbow_36_32_32, rainbow_68_32_48, rainbow_96_36_64, rainbow_last }
 Possible rainbow parameters sets. More...
 

Functions

PQLR_API rainbow_t rainbow_new (rainbow_parameterset_t parameterset)
 Creates new rainbow instance with selected parameter set. More...
 
PQLR_API void rainbow_free (rainbow_t rainbow)
 Frees rainbow instance and all corresponding resources. More...
 
PQLR_API rainbow_t rainbow_duplicate (const rainbow_t rainbow)
 Duplicates context of rainbow instance. More...
 
PQLR_API pqlr_t rainbow_to_pqlr (rainbow_t rainbow)
 Casts rainbow instance to pqlr instance. More...
 
PQLR_API size_t rainbow_get_public_key_bytes_len (rainbow_t rainbow)
 Obtains public key buffer length in bytes for current rainbow instance. More...
 
PQLR_API size_t rainbow_get_secret_key_bytes_len (rainbow_t rainbow)
 Obtains secret key buffer length in bytes for current rainbow instance. More...
 
PQLR_API size_t rainbow_get_signature_bytes_len (rainbow_t rainbow)
 Obtains signature buffer length in bytes for current rainbow instance. More...
 
PQLR_API void rainbow_generate_keys (const rainbow_t rainbow, uint8_t *sk, uint8_t *pk)
 Generates random secret key and public key for given context. More...
 
PQLR_API int rainbow_verify (const rainbow_t rainbow, 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...
 
PQLR_API void rainbow_sign (const rainbow_t rainbow, 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...
 

Detailed Description

This module provides Rainbow algorithm implementation, which is a stateless signature scheme based on multivariate public key cryptosystem (MPKC).

General usage

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

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

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

Example code is listed below:

#include <stdlib.h>
void use_new()
{
// free resources
rainbow_free(rainbow);
}
void use_generate_keys()
{
const int sk_len = rainbow_get_secret_key_bytes_len(rainbow);
const int pk_len = rainbow_get_public_key_bytes_len(rainbow);
uint8_t* sk = (uint8_t*)calloc(sk_len, sizeof(uint8_t));
uint8_t* pk = (uint8_t*)calloc(pk_len, sizeof(uint8_t));
rainbow_generate_keys(rainbow, sk, pk);
// free resources
free(pk);
free(sk);
rainbow_free(rainbow);
}
void use_sign()
{
const int sk_len = rainbow_get_secret_key_bytes_len(rainbow);
const int pk_len = rainbow_get_public_key_bytes_len(rainbow);
uint8_t* sk = (uint8_t*)calloc(sk_len, sizeof(uint8_t));
uint8_t* pk = (uint8_t*)calloc(pk_len, sizeof(uint8_t));
rainbow_generate_keys(rainbow, sk, pk);
size_t sig_len = rainbow_get_signature_bytes_len(rainbow);
uint8_t* sig = (uint8_t*)calloc(sig_len, sizeof(uint8_t));
unsigned char msg[] = "test";
rainbow_sign(rainbow, sk, msg, sizeof(msg), sig, &sig_len);
// free resources
free(sig);
free(sk);
rainbow_free(rainbow);
}
void use_verify()
{
const int pk_len = rainbow_get_public_key_bytes_len(rainbow);
const int sig_len = rainbow_get_signature_bytes_len(rainbow);
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 = rainbow_verify(rainbow, pk, sig, msg, sizeof(msg));
// free resources
free(sig);
free(pk);
rainbow_free(rainbow);
}
int main()
{
use_new();
use_generate_keys();
use_sign();
use_verify();
}

Typedef Documentation

◆ rainbow_t

typedef struct rainbow_st* rainbow_t

Rainbow algorithm instance handle.

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

Enumeration Type Documentation

◆ rainbow_parameterset_t

Possible rainbow parameters sets.

Enumerator
rainbow_36_32_32 
rainbow_68_32_48 
rainbow_96_36_64 
rainbow_last 

Function Documentation

◆ rainbow_duplicate()

PQLR_API rainbow_t rainbow_duplicate ( const rainbow_t  rainbow)

Duplicates context of rainbow instance.

Parameters
rainbowinstance to duplicate
Returns
new instance with a duplicated context

◆ rainbow_free()

PQLR_API void rainbow_free ( rainbow_t  rainbow)

Frees rainbow instance and all corresponding resources.

Parameters
[in]rainbowinstance to free
See also
rainbow_t
rainbow_new

◆ rainbow_generate_keys()

PQLR_API void rainbow_generate_keys ( const rainbow_t  rainbow,
uint8_t *  sk,
uint8_t *  pk 
)

Generates random secret key and public key for given context.

Usage:

const int sk_len = rainbow_get_secret_key_bytes_len(rainbow);
const int pk_len = rainbow_get_public_key_bytes_len(rainbow);
uint8_t* sk = (uint8_t*)calloc(sk_len, sizeof(uint8_t));
uint8_t* pk = (uint8_t*)calloc(pk_len, sizeof(uint8_t));
rainbow_generate_keys(rainbow, sk, pk);
Parameters
[in]rainbowInstance of rainbow created with rainbow_new(). If NULL, the fatal error occurs.
[out]skContiguous array to receive secret key, of size rainbow_get_secret_key_bytes_len. If NULL, the fatal error occurs.
[out]pkContiguous array to receive public key, of size rainbow_get_public_key_bytes_len. If NULL, the fatal error occurs.
See also
rainbow_new
rainbow_get_secret_key_bytes_len
rainbow_get_public_key_bytes_len

◆ rainbow_get_public_key_bytes_len()

PQLR_API size_t rainbow_get_public_key_bytes_len ( rainbow_t  rainbow)

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

Parameters
rainbowinitialized rainbow instance
See also
rainbow_t
rainbow_new
Returns
public key buffer length in bytes

◆ rainbow_get_secret_key_bytes_len()

PQLR_API size_t rainbow_get_secret_key_bytes_len ( rainbow_t  rainbow)

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

Parameters
[in]rainbowinitialized rainbow instance
See also
rainbow_t
rainbow_new
Returns
secret key buffer length in bytes

◆ rainbow_get_signature_bytes_len()

PQLR_API size_t rainbow_get_signature_bytes_len ( rainbow_t  rainbow)

Obtains signature buffer length in bytes for current rainbow instance.

Parameters
rainbowinitialized rainbow instance
See also
rainbow_t
rainbow_new
Returns
signature buffer length in bytes

◆ rainbow_new()

PQLR_API rainbow_t rainbow_new ( rainbow_parameterset_t  parameterset)

Creates new rainbow instance with selected parameter set.

Usage:

Parameters
[in]parametersetavailable set of parameters for rainbow algorithm
Returns
initialized rainbow instance or NULL if out of memory

◆ rainbow_sign()

PQLR_API void rainbow_sign ( const rainbow_t  rainbow,
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 = rainbow_get_secret_key_bytes_len(rainbow);
const int pk_len = rainbow_get_public_key_bytes_len(rainbow);
uint8_t* sk = (uint8_t*)calloc(sk_len, sizeof(uint8_t));
uint8_t* pk = (uint8_t*)calloc(pk_len, sizeof(uint8_t));
rainbow_generate_keys(rainbow, sk, pk);
size_t sig_len = rainbow_get_signature_bytes_len(rainbow);
uint8_t* sig = (uint8_t*)calloc(sig_len, sizeof(uint8_t));
unsigned char msg[] = "test";
rainbow_sign(rainbow, sk, msg, sizeof(msg), sig, &sig_len);
Parameters
rainbowInstance of rainbow created with rainbow_new(). If NULL, the fatal error occurs.
skSecret key, the contiguous array of size rainbow_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
rainbow_get_secret_key_bytes_len

◆ rainbow_to_pqlr()

PQLR_API pqlr_t rainbow_to_pqlr ( rainbow_t  rainbow)

Casts rainbow instance to pqlr instance.

Parameters
[in]rainbowinitialized rainbow instance
Note
this pqlr instance will be released by rainbow_free
See also
rainbow_t
pqlr_t
rainbow_free
Returns
operable pqlr instance or NULL if rainbow is NULL

◆ rainbow_verify()

PQLR_API int rainbow_verify ( const rainbow_t  rainbow,
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:

const int pk_len = rainbow_get_public_key_bytes_len(rainbow);
const int sig_len = rainbow_get_signature_bytes_len(rainbow);
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 = rainbow_verify(rainbow, pk, sig, msg, sizeof(msg));
Parameters
rainbowContext, initialized with rainbow_new(). If NULL, the fatal error occurs.
pkPublic key, the contiguous array of size rainbow_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.
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
rainbow_get_signature_bytes_len
rainbow_get_public_key_bytes_len