iqr_rng.h File Reference

ISARA Radiate Quantum-Safe Library's Random Number Generator object APIs. More...

Data Structures
struct	iqr_RNGCallbacks

Typedefs
typedef struct iqr_RNG_struct	iqr_RNG

Functions
IQR_API iqr_retval	iqr_RNGCreate (const iqr_Context *ctx, const iqr_RNGCallbacks *cb, iqr_RNG **rng)
IQR_API_UNENFORCED_RETURN iqr_retval	iqr_RNGDestroy (iqr_RNG **rng)
IQR_API iqr_retval	iqr_RNGCreateHMACDRBG (const iqr_Context *ctx, iqr_HashAlgorithmType hash_algo, iqr_RNG **rng)
IQR_API iqr_retval	iqr_RNGInitialize (iqr_RNG *rng, const uint8_t *seed, size_t seed_size)
IQR_API iqr_retval	iqr_RNGReseed (const iqr_RNG *rng, const uint8_t *entropy, size_t entropy_size)
IQR_API iqr_retval	iqr_RNGGetBytes (const iqr_RNG *rng, uint8_t *buf, size_t buf_size)

Typedef Documentation

iqr_RNG

typedef struct iqr_RNG_struct iqr_RNG

Random Number Generator object.

Function Documentation

iqr_RNGCreate()

IQR_API iqr_retval iqr_RNGCreate	(	const iqr_Context *	ctx,
		const iqr_RNGCallbacks *	cb,
		iqr_RNG **	rng
	)

Create and initialize a Random Number Generator.

Alternatively, you can use iqr_RNGCreateHMACDRBG() to create an HMAC-DRBG random number generator.

*rng must be set to NULL before calling iqr_RNGCreate().

Parameters

[in]	ctx	A Context.
[in]	cb	A set of function pointers implementing the Random Number Generator.
[out]	rng	A pointer to a Random Number Generator object.

Returns

IQR_OK on success, or another value from iqr_retval.h if an error occurs.

iqr_RNGCreateHMACDRBG()

IQR_API iqr_retval iqr_RNGCreateHMACDRBG	(	const iqr_Context *	ctx,
		iqr_HashAlgorithmType	hash_algo,
		iqr_RNG **	rng
	)

Create an HMAC-DRBG Random Number Generator.

This function creates an iqr_RNG object, and is analogous to iqr_RNGCreate().

You must call iqr_HashRegisterCallbacks() to set the Hash implementation before calling this function. Otherwise IQR_ENOTREGISTERED is returned.

*rng must be set to NULL before calling iqr_RNGCreateHMACDRBG().

HMAC-DRBG needs to be reseeded after a large number (2^48^) of iqr_RNGGetBytes() requests. If you're adhering to specific standards or protocols that specify when to reseed, you may need to do it more frequently.

Parameters

[in]	ctx	A Context object.
[in]	hash_algo	The Hash algorithm to use in the HMAC-DRBG.
[out]	rng	Where to store the allocated RNG object.

Returns

IQR_OK on success, or another value from iqr_retval.h if an error occurs.

iqr_RNGDestroy()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_RNGDestroy

(

iqr_RNG **

rng

)

Clear and deallocate a Random Number Generator.

This can also return any of the return values from your cleanup() callback. If cleanup() fails, nothing in the rng is modified.

rng is set to NULL prior to returning.

All internal iqr_RNG buffers are cleared and deallocated during the call to iqr_RNGDestroy().

Parameters

[in,out]

rng

A pointer to a Random Number Generator object.

Returns

IQR_OK on success, or another value from iqr_retval.h if an error occurs.

iqr_RNGGetBytes()

IQR_API iqr_retval iqr_RNGGetBytes	(	const iqr_RNG *	rng,
		uint8_t *	buf,
		size_t	buf_size
	)

Provide random bytes in the given buffer.

This function will return IQR_ERESEED when the RNG requires reseeding. See iqr_RNGReseed() for details. This can also return any of the return values from your getbytes() callback.

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

Parameters

[in]	rng	A seeded random number generator.
[out]	buf	A buffer to store the random bytes. Cannot be NULL.
[in]	buf_size	The number of bytes to write into the buf. Cannot be 0.

Returns

IQR_OK on success, or another value from iqr_retval.h if an error occurs.

iqr_RNGInitialize()

IQR_API iqr_retval iqr_RNGInitialize	(	iqr_RNG *	rng,
		const uint8_t *	seed,
		size_t	seed_size
	)

Initialize a Random Number Generator with the given initial seed data.

This can also return any of the return values from your initialize() callback.

Note

The seed_size should be at least as large as the desired security strength. For example, if you're using HMAC-DRBG with SHA2-256, you must provide at least 256/8 = 32 bytes of data in seed to reach 256 bits of classical security.

Parameters

[in]	rng	A Random Number Generator.
[in]	seed	A buffer containing seed data. Cannot be NULL.
[in]	seed_size	The number of bytes in seed. Cannot be 0.

Returns

IQR_OK on success, or another value from iqr_retval.h if an error occurs.

iqr_RNGReseed()

IQR_API iqr_retval iqr_RNGReseed	(	const iqr_RNG *	rng,
		const uint8_t *	entropy,
		size_t	entropy_size
	)

Reseed a Random Number Generator with additional data.

This can also return any of the return values from your reseed() callback.

Note

The entropy_size should be at least as large as the desired security strength. For example, if you're using HMAC-DRBG with SHA2-256, you must provide at least 256/8 = 32 bytes of data in entropy to reach 256 bits of classical security.

Parameters

[in]	rng	A Random Number Generator.
[in]	entropy	A buffer containing additional seed data. Cannot be NULL.
[in]	entropy_size	The number of bytes in entropy. Cannot be 0.

Returns

IQR_OK on success, or another value from iqr_retval.h if an error occurs.

Detailed Description

ISARA Radiate Quantum-Safe Library's Random Number Generator object APIs.

The Random Number Generator (RNG) object provides a generic interface for algorithms that generate random data, such as HMAC-DRBG. RNG objects are created from a set of callbacks and then passed in to other algorithms.

Copyright

Copyright (C) 2015-2023, ISARA Corporation, All Rights Reserved.

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.