iqr_rng.h File Reference

ISARA Radiate Security Solution Suite's Random Number Generator object APIs. More...

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 *buf, size_t buf_size)
IQR_API iqr_retval	iqr_RNGReseed (const iqr_RNG *rng, const uint8_t *buf, size_t buf_size)
IQR_API iqr_retval	iqr_RNGGetBytes (const iqr_RNG *rng, uint8_t *buf, size_t buf_size)

Macro Definition Documentation

IQR_SHAKE_128_SIZE

#define IQR_SHAKE_128_SIZE   16

Size of the internal SHAKE block in bytes for 128 bits of randomness.

IQR_SHAKE_256_SIZE

#define IQR_SHAKE_256_SIZE   32

Size of the internal SHAKE block in bytes for 256 bits of randomness.

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.

*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 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 is returned.

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

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().

*rng must be set to NULL before calling iqr_RNGCreateSHAKE.

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

)

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

iqr_RNGInitialize()

IQR_API iqr_retval iqr_RNGInitialize	(	iqr_RNG *	rng,
		const uint8_t *	buf,
		size_t	buf_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

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

When FIPS 140-2 mode is enabled, FIPS 140-2 Approved RNGs (HMAC-DRBG and SHAKE) don't allow an initialization buffer of all 0x00 bytes; you must provide valid seed data.

Note

SHAKE can be initialized with a buf_size of 0, although this is not recommended. FIPS 140-2 assumes this behaviour.

Parameters

[in]	rng	A Random Number Generator.
[in]	buf	A buffer containing seed data. Cannot be NULL.
[in]	buf_size	The number of bytes in buf. 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 *	buf,
		size_t	buf_size
	)

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 buf_size should be at least as large as the desired security strength. For example, if you're using SHA2-256, you must provide at least 256/8 = 32 bytes of data in buf to reach 256 bits of classical security.

FIPS 140-2 Approved RNGs (HMAC-DRBG and SHAKE) don't allow a reseed buffer of all 0x00 bytes; you must provide valid seed data.

Parameters

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

Returns

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

Detailed Description

ISARA Radiate Security Solution Suite'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 2015-2018, 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.