ISARA Radiate Security Solution Suite's Rainbow signature scheme. More...

Typedefs
typedef struct iqr_RainbowParams_struct	iqr_RainbowParams

typedef struct iqr_RainbowPublicKey_struct	iqr_RainbowPublicKey

typedef struct iqr_RainbowPrivateKey_struct	iqr_RainbowPrivateKey

typedef struct iqr_RainbowVariant_struct	iqr_RainbowVariant

Functions
IQR_API iqr_retval	iqr_RainbowCreateParams (const iqr_Context ctx, const iqr_RainbowVariant variant, iqr_RainbowParams **params)

IQR_API_UNENFORCED_RETURN iqr_retval	iqr_RainbowDestroyParams (iqr_RainbowParams **params)

IQR_API iqr_retval	iqr_RainbowCreateKeyPair (const iqr_RainbowParams params, const iqr_RNG rng, iqr_RainbowPublicKey public_key, iqr_RainbowPrivateKey private_key)

IQR_API iqr_retval	iqr_RainbowImportPrivateKey (const iqr_RainbowParams params, const uint8_t buf, size_t buf_size, iqr_RainbowPrivateKey **private_key)

IQR_API iqr_retval	iqr_RainbowExportPrivateKey (const iqr_RainbowPrivateKey private_key, uint8_t buf, size_t buf_size)

IQR_API iqr_retval	iqr_RainbowImportPublicKey (const iqr_RainbowParams params, const uint8_t buf, size_t buf_size, iqr_RainbowPublicKey **public_key)

IQR_API iqr_retval	iqr_RainbowExportPublicKey (const iqr_RainbowPublicKey public_key, uint8_t buf, size_t buf_size)

IQR_API_UNENFORCED_RETURN iqr_retval	iqr_RainbowDestroyPublicKey (iqr_RainbowPublicKey **public_key)

IQR_API_UNENFORCED_RETURN iqr_retval	iqr_RainbowDestroyPrivateKey (iqr_RainbowPrivateKey **private_key)

IQR_API iqr_retval	iqr_RainbowGetPrivateKeySize (const iqr_RainbowParams params, size_t private_key_size)

IQR_API iqr_retval	iqr_RainbowGetPublicKeySize (const iqr_RainbowParams params, size_t public_key_size)

IQR_API iqr_retval	iqr_RainbowGetSignatureSize (const iqr_RainbowParams params, size_t sig_size)

IQR_API iqr_retval	iqr_RainbowSign (const iqr_RainbowPrivateKey private_key, const iqr_RNG rng, const uint8_t message, size_t message_size, uint8_t sig, size_t sig_size)

IQR_API iqr_retval	iqr_RainbowVerify (const iqr_RainbowPublicKey public_key, const uint8_t message, size_t message_size, const uint8_t *sig, size_t sig_size)

Variables
IQR_EXTERN const iqr_RainbowVariant	IQR_RAINBOW_GF16_56_48_48

IQR_EXTERN const iqr_RainbowVariant	IQR_RAINBOW_GF16_76_64_64

IQR_EXTERN const iqr_RainbowVariant	IQR_RAINBOW_GF31_64_32_48

IQR_EXTERN const iqr_RainbowVariant	IQR_RAINBOW_GF31_84_56_56

IQR_EXTERN const iqr_RainbowVariant	IQR_RAINBOW_GF256_68_36_36

IQR_EXTERN const iqr_RainbowVariant	IQR_RAINBOW_GF256_92_48_48

Typedef Documentation

◆ iqr_RainbowParams

typedef struct iqr_RainbowParams_struct iqr_RainbowParams

The Rainbow algorithm's domain parameters.

◆ iqr_RainbowPrivateKey

typedef struct iqr_RainbowPrivateKey_struct iqr_RainbowPrivateKey

The Rainbow private key.

◆ iqr_RainbowPublicKey

typedef struct iqr_RainbowPublicKey_struct iqr_RainbowPublicKey

The Rainbow public key.

◆ iqr_RainbowVariant

typedef struct iqr_RainbowVariant_struct iqr_RainbowVariant

Rainbow variants.

Function Documentation

◆ iqr_RainbowCreateKeyPair()

IQR_API iqr_retval iqr_RainbowCreateKeyPair	(	const iqr_RainbowParams *	params,
		const iqr_RNG *	rng,
		iqr_RainbowPublicKey **	public_key,
		iqr_RainbowPrivateKey **	private_key
	)

Generate a Rainbow private/public key pair.

The iqr_RainbowCreateKeyPair() function calls the watchdog callback (see iqr_watchdog.h).

The rng must be initialized before being passed to iqr_RainbowCreateKeyPair().

*public_key and *private_key must be set to NULL before calling iqr_RainbowCreateKeyPair().

Note: If iqr_RainbowCreateKeyPair() repeatedly returns IQR_ERESEED, your random number generator isn't producing uniformly random values. Use a cryptographically strong RNG (such as HMAC-DRBG) with sufficient entropy.

Parameters

[in]	params	The parameters to use.
[in]	rng	A seeded random number generator.
[out]	public_key	The resulting `iqr_RainbowPublicKey` object.
[out]	private_key	The resulting `iqr_RainbowPrivateKey` object.

Returns: IQR_OK on success, or a value from iqr_retval.h when an error occurs.

◆ iqr_RainbowCreateParams()

IQR_API iqr_retval iqr_RainbowCreateParams	(	const iqr_Context *	ctx,
		const iqr_RainbowVariant *	variant,
		iqr_RainbowParams **	params
	)

Create a Rainbow parameters object that encapsulates the domain parameters for the Rainbow signature scheme.

Note: You must register a SHA2-384 and/or a SHA2-512 implementation (Depending on which parameter sets are used.) by calling iqr_HashRegisterCallbacks() before using the Rainbow API.

*params must be set to NULL before calling iqr_RainbowCreateParams().

Parameters

[in]	ctx	A Context object.
[in]	variant	Rainbow variant to use.
[out]	params	The `iqr_RainbowParams` output.

Returns: IQR_OK on success, or a value from iqr_retval.h when an error occurs.

◆ iqr_RainbowDestroyParams()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_RainbowDestroyParams ( iqr_RainbowParams ** params )

Clear and deallocate a Rainbow parameters object.

params will be set to NULL before returning.

All internal iqr_RainbowParams buffers are cleared and deallocated during the call to iqr_RainbowDestroyParams(). The iqr_RainbowParams object does not store any cryptographic material.

Parameters

[in,out] params The iqr_RainbowParams instance to destroy.

Returns: IQR_OK on success, or a value from iqr_retval.h when an error occurs.

◆ iqr_RainbowDestroyPrivateKey()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_RainbowDestroyPrivateKey ( iqr_RainbowPrivateKey ** private_key )

Clear and deallocate a Rainbow private key.

private_key will be set to NULL prior to returning.

The private key's data is cleared before its internal buffers are deallocated.

Parameters

[in,out] private_key The iqr_RainbowPrivateKey object to destroy.

Returns: IQR_OK on success, or a value from iqr_retval.h when an error occurs.

◆ iqr_RainbowDestroyPublicKey()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_RainbowDestroyPublicKey ( iqr_RainbowPublicKey ** public_key )

Clear and deallocate a Rainbow public key.

public_key will be set to NULL prior to returning.

Parameters

[in,out] public_key The iqr_RainbowPublicKey object to destroy.

Returns: IQR_OK on success, or a value from iqr_retval.h when an error occurs.

◆ iqr_RainbowExportPrivateKey()

IQR_API iqr_retval iqr_RainbowExportPrivateKey	(	const iqr_RainbowPrivateKey *	private_key,
		uint8_t *	buf,
		size_t	buf_size
	)

Export the Rainbow private key's data into a buffer.

Be sure to safely wipe and discard buf when you're done using it.

Parameters

[in]	private_key	The private key object.
[out]	buf	The destination buffer.
[in]	buf_size	The size of buf in bytes. Must be exactly the size returned by `iqr_RainbowGetPrivateKeySize()` bytes.

Returns: IQR_OK on success, or a value from iqr_retval.h when an error occurs.

◆ iqr_RainbowExportPublicKey()

IQR_API iqr_retval iqr_RainbowExportPublicKey	(	const iqr_RainbowPublicKey *	public_key,
		uint8_t *	buf,
		size_t	buf_size
	)

Export the Rainbow public key's data into a buffer.

Parameters

[in]	public_key	The public key object.
[out]	buf	The destination buffer.
[in]	buf_size	The size of buf in bytes. Must be exactly the size returned by `iqr_RainbowGetPublicKeySize()` bytes.

Returns: IQR_OK on success, or a value from iqr_retval.h when an error occurs.

◆ iqr_RainbowGetPrivateKeySize()

IQR_API iqr_retval iqr_RainbowGetPrivateKeySize	(	const iqr_RainbowParams *	params,
		size_t *	private_key_size
	)

Retrieves the size of the Rainbow private key, in bytes.

Parameters

[in]	params	Rainbow domain parameters.
[out]	private_key_size	The size of the private key in bytes.

Returns: IQR_OK on success, or a value from iqr_retval.h when an error occurs.

◆ iqr_RainbowGetPublicKeySize()

IQR_API iqr_retval iqr_RainbowGetPublicKeySize	(	const iqr_RainbowParams *	params,
		size_t *	public_key_size
	)

Retrieve the size of the Rainbow public key, in bytes.

Parameters

[in]	params	Rainbow domain parameters.
[out]	public_key_size	The size of the public key in bytes.

Returns: IQR_OK on success, or a value from iqr_retval.h when an error occurs.

◆ iqr_RainbowGetSignatureSize()

IQR_API iqr_retval iqr_RainbowGetSignatureSize	(	const iqr_RainbowParams *	params,
		size_t *	sig_size
	)

Get the size of the signature.

Parameters

[in]	params	Rainbow domain parameters.
[out]	sig_size	The size of the Rainbow signature for the given private key in bytes.

Returns: IQR_OK on success, or a value from iqr_retval.h when an error occurs.

◆ iqr_RainbowImportPrivateKey()

IQR_API iqr_retval iqr_RainbowImportPrivateKey	(	const iqr_RainbowParams *	params,
		const uint8_t *	buf,
		size_t	buf_size,
		iqr_RainbowPrivateKey **	private_key
	)

Import a Rainbow private key object from a buffer.

*private_key must be set to NULL before calling iqr_RainbowImportPrivateKey(). Be sure to safely wipe and discard buf after calling this function.

Parameters

[in]	params	Rainbow parameters. Must be the same as when the keys were created.
[in]	buf	A buffer that contains a private key.
[in]	buf_size	The size of buf in bytes. Must be exactly the size returned by `iqr_RainbowGetPrivateKeySize()` bytes.
[out]	private_key	The resulting `iqr_RainbowPrivateKey` object.

Returns: IQR_OK on success, or a value from iqr_retval.h when an error occurs.

◆ iqr_RainbowImportPublicKey()

IQR_API iqr_retval iqr_RainbowImportPublicKey	(	const iqr_RainbowParams *	params,
		const uint8_t *	buf,
		size_t	buf_size,
		iqr_RainbowPublicKey **	public_key
	)

Import a Rainbow public key object from a buffer.

*public_key must be set to NULL before calling iqr_RainbowImportPublicKey().

Parameters

[in]	params	Rainbow parameters. Must be the same as when the keys were created.
[in]	buf	A buffer containing the public key.
[in]	buf_size	The size of buf in bytes. Must be exactly the size returned by `iqr_RainbowGetPublicKeySize()` bytes.
[out]	public_key	The resulting `iqr_RainbowPublickey` object.

Returns: IQR_OK on success, or a value from iqr_retval.h when an error occurs.

◆ iqr_RainbowSign()

IQR_API iqr_retval iqr_RainbowSign	(	const iqr_RainbowPrivateKey *	private_key,
		const iqr_RNG *	rng,
		const uint8_t *	message,
		size_t	message_size,
		uint8_t *	sig,
		size_t	sig_size
	)

Sign a message using a Rainbow private key.

Note: If the message is a digest of a hash function it must be 48 bytes or longer to be quantum-safe.; If iqr_RainbowSign() repeatedly returns IQR_ERESEED, your random number generator isn't producing uniformly random values. Use a cryptographically strong RNG (such as HMAC-DRBG) with sufficient entropy.

All internal buffers are cleared and deallocated before the call to iqr_RainbowSign() returns.

Parameters

[in]	private_key	The private key.
[in]	rng	A seeded random number generator.
[in]	message	The message to be signed.
[in]	message_size	The size of message in bytes.
[out]	sig	The buffer receiving the resulting signature.
[in]	sig_size	The size of sig in bytes. Must be exactly the size returned by `iqr_RainbowGetSignatureSize()`.

Returns: IQR_OK on success, or a value from iqr_retval.h when an error occurs.

◆ iqr_RainbowVerify()

IQR_API iqr_retval iqr_RainbowVerify	(	const iqr_RainbowPublicKey *	public_key,
		const uint8_t *	message,
		size_t	message_size,
		const uint8_t *	sig,
		size_t	sig_size
	)

Verify the signature of a message using a Rainbow public key.

Note: If the message is a digest of a hash function it must be 48 bytes or longer to be quantum-safe.

All internal buffers are cleared and deallocated before the call to iqr_RainbowVerify() returns.

Parameters

[in]	public_key	The public key.
[in]	message	The message to verify.
[in]	message_size	The size of message in bytes.
[in]	sig	The signature to verify.
[in]	sig_size	The size of sig in bytes. Must be exactly the size returned by `iqr_RainbowGetSignatureSize()`.

Returns: IQR_OK on success, or a value from iqr_retval.h when an error occurs.

Variable Documentation

◆ IQR_RAINBOW_GF16_56_48_48

IQR_EXTERN const iqr_RainbowVariant IQR_RAINBOW_GF16_56_48_48

IVa (F, v1, o1, o2) = (GF(16), 56, 48, 48) Uses SHA2-384.

◆ IQR_RAINBOW_GF16_76_64_64

IQR_EXTERN const iqr_RainbowVariant IQR_RAINBOW_GF16_76_64_64

VIa (F, v1, o1, o2) = (GF(16), 76, 64, 64) Uses SHA2-512.

◆ IQR_RAINBOW_GF256_68_36_36

IQR_EXTERN const iqr_RainbowVariant IQR_RAINBOW_GF256_68_36_36

IIIc (F, v1, o1, o2) = (GF(256), 68, 36, 36) Uses SHA2-384.

◆ IQR_RAINBOW_GF256_92_48_48

IQR_EXTERN const iqr_RainbowVariant IQR_RAINBOW_GF256_92_48_48

Vc (F, v1, o1, o2) = (GF(256), 92, 48, 48) Uses SHA2-512.

◆ IQR_RAINBOW_GF31_64_32_48

IQR_EXTERN const iqr_RainbowVariant IQR_RAINBOW_GF31_64_32_48

IIIb (F, v1, o1, o2) = (GF(31), 64, 32, 48) Uses SHA2-384.

◆ IQR_RAINBOW_GF31_84_56_56

IQR_EXTERN const iqr_RainbowVariant IQR_RAINBOW_GF31_84_56_56

VIb (F, v1, o1, o2) = (GF(31), 84, 56, 56) Uses SHA2-512.

Detailed Description

ISARA Radiate Security Solution Suite's Rainbow signature scheme.

An implementation of Rainbow signature scheme as defined in Rainbow.

This header contains the functions and parameters necessary to create a key pair as well as create and verify a Rainbow signature. The two main functions are iqr_RainbowSign() and iqr_RainbowVerify(). The rest of the functions let you create and manipulate Rainbow parameters and keys.

Rainbow parameter sets are formatted as IQR_RAINBOW_GFf_V1_O1_O2, where "f" indicates the Galois field, "V1" is the number of vinegar variables in the first layer, "O1" is the number of oil variables in the first layer, and "O2" is the number of oil variables in the second layer.

These are organized in increasing strength, according to the NIST Post Quantum Cryptography contest groups; group "VI" in the Rainbow specification should be read as group "V" as there is no group "VI" and these parameters are at least as strong as (GF(256), 92, 48, 48).

License: The code and other content set out herein is not in the public domain, is considered a trade secret and is confidential to ISARA Corporation. Use, reproduction or distribution, in whole or in part, of such code or other content is strictly prohibited except by express written permission of ISARA Corporation. Please contact ISARA Corporation at info@.nosp@m.isar.nosp@m.a.com for more information.

ISARA Radiate Security Solution Suite Toolkit Edition Version 1.5

Typedefs

Functions

Variables

Typedef Documentation

◆ iqr_RainbowParams

◆ iqr_RainbowPrivateKey

◆ iqr_RainbowPublicKey

◆ iqr_RainbowVariant

Function Documentation

◆ iqr_RainbowCreateKeyPair()

◆ iqr_RainbowCreateParams()

◆ iqr_RainbowDestroyParams()

◆ iqr_RainbowDestroyPrivateKey()

◆ iqr_RainbowDestroyPublicKey()

◆ iqr_RainbowExportPrivateKey()

◆ iqr_RainbowExportPublicKey()

◆ iqr_RainbowGetPrivateKeySize()

◆ iqr_RainbowGetPublicKeySize()

◆ iqr_RainbowGetSignatureSize()

◆ iqr_RainbowImportPrivateKey()

◆ iqr_RainbowImportPublicKey()

◆ iqr_RainbowSign()

◆ iqr_RainbowVerify()

Variable Documentation

◆ IQR_RAINBOW_GF16_56_48_48

◆ IQR_RAINBOW_GF16_76_64_64

◆ IQR_RAINBOW_GF256_68_36_36

◆ IQR_RAINBOW_GF256_92_48_48

◆ IQR_RAINBOW_GF31_64_32_48

◆ IQR_RAINBOW_GF31_84_56_56

Detailed Description