iqr_rng.h File Reference

Data Structures
struct	iqr_RNGCallbacks

Macros
#define	IQR_SHAKE_128_SIZE   16
#define	IQR_SHAKE_256_SIZE   32

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_RNGCreateSHAKE (const iqr_Context *ctx, size_t shake_size, iqr_RNG **rng)
IQR_API iqr_retval	iqr_RNGInitialize (iqr_RNG *rng, const uint8_t *buffer, size_t length)
IQR_API iqr_retval	iqr_RNGReseed (const iqr_RNG *rng, const uint8_t *buffer, size_t length)
IQR_API iqr_retval	iqr_RNGGetBytes (const iqr_RNG *rng, uint8_t *buffer, size_t num_bytes)

Macro Definition Documentation

IQR_SHAKE_128_SIZE

#define IQR_SHAKE_128_SIZE   16

Valid sizes for SHAKE-based RNGs.

IQR_SHAKE_256_SIZE

#define IQR_SHAKE_256_SIZE   32

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() or iqr_RNGCreateSHAKE to create an HMAC-DRBG or SHAKE random number generator.

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 a value from iqr_retval.h when 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 will be returned.

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 a value from iqr_retval.h when an error occurs.

iqr_RNGCreateSHAKE()

IQR_API iqr_retval iqr_RNGCreateSHAKE	(	const iqr_Context *	ctx,
		size_t	shake_size,
		iqr_RNG **	rng
	)

Create a SHAKE Random Number Generator.

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

Parameters

[in]	ctx	A Context object.
[in]	shake_size	Either IQR_SHAKE_128_SIZE or IQR_SHAKE_256_SIZE.
[out]	rng	Where to store the allocated RNG object.

Returns

IQR_OK for success, or a value from iqr_retval.h when an error occurs.

iqr_RNGDestroy()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_RNGDestroy

(

iqr_RNG **

rng

)

Zero 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 will be set to NULL prior to returning.

Parameters

[in,out]

rng

A pointer to a Random Number Generator object.

Returns

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

iqr_RNGGetBytes()

IQR_API iqr_retval iqr_RNGGetBytes	(	const iqr_RNG *	rng,
		uint8_t *	buffer,
		size_t	num_bytes
	)

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.

Parameters

[in]	rng	A Random Number Generator.
[out]	buffer	A buffer to store the random bytes. Cannot be NULL.
[in]	num_bytes	The number of bytes to write into the buffer. Cannot be 0.

Returns

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

iqr_RNGInitialize()

IQR_API iqr_retval iqr_RNGInitialize	(	iqr_RNG *	rng,
		const uint8_t *	buffer,
		size_t	length
	)

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

For HMAC-DRBG, the length should be at least as large as the desired security strength. For example, if you're using SHA-256, you should provide at least 256 / 8 = 32 bytes of data in buffer.

Parameters

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

Returns

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

iqr_RNGReseed()

IQR_API iqr_retval iqr_RNGReseed	(	const iqr_RNG *	rng,
		const uint8_t *	buffer,
		size_t	length
	)

Reseed a Random Number Generator with additional data.

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

Note

For HMAC-DRBG, the length should be at least as large as the desired security strength. For example, if you're using SHA-256, you should provide at least 256 / 8 = 32 bytes of data in buffer.

Parameters

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

Returns

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

Detailed Description

ISARA Toolkit'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 implementations are registered globally via the Context object. Once you've registered the desired RNG implementation, the rest of the library can create RNG objects as needed.

Copyright

Copyright 2015-2016, 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.