Detailed Description

RNG driver header.

Overview

The Random Number Generator (RNG) module generates random data of variable lengths from a pool of entropy. The pool of entropy is maintained by the driver using implementation-specific sources of entropy. The output is suitable for applications requiring cryptographically random data such as keying material for private or symmetric keys.

Usage

Initialization

Unlike most drivers, there is a global instance of RNG driver data that is always available once RNG_init() is called. This data will contain the entropy pool and any needed state information required to refill the pool. RNG_init() should be called once before using other RNG driver APIs.

Note: Some implementations restrict when RNG_init() may be called. Check the implementation's documentation for more information.

Before starting a RNG operation

Before starting a RNG operation, the application must do the following:

Call RNG_init() to initialize the driver's global instance data.
Call RNG_Params_init() to initialize the RNG_Params to default values.
Modify the RNG_Params as desired.
Call RNG_open() to open an instance of the driver.

Note: Some implementations restrict when RNG_init() may be called. Check the implementation's documentation for more information.

Entropy Pool Management

At any time after calling RNG_init(), the application may call RNG_fillPoolIfLessThan() to add entropy to the pool which will then make future requests for entropy execute faster. Note that the driver never automatically refills the pool. However, if the pool is empty, the RNG driver will still generate entropy upon request (for example when RNG_getRandomBits() is called).

The application is responsible for deciding when it is appropriate to spend the time and energy to refill the pool. One suggested location to do so is the idle thread.

RNG operations

Use RNG_getRandomBits() to obtain random bits from the entropy pool and copy them to a buffer/array. The caller must allocate memory sufficient to hold at least the number of bits of random data requested.

After the RNG operation completes

After the RNG operation completes, the application should either start another operation or close the driver by calling RNG_close(). Note that the singleton instance of the driver, along with its associated pool of entropy will still exist and will be used by any future RNG_open() calls. Note that closing the driver instance may not be strictly required, but is good practice.

Security

Data Protection

The entropy pool and any required state to generate more entropy is maintained in memory, in the driver's global instance data. The entirety of this data is stored in two global variables called RNG_instanceData and RNG_instancePool. It is up to the system to provide adequate protection (primarily confidentiality and integrity) of these in-memory assets.

Timing Side Channels

Functions which provide for generation of a value within a range use an algorithm which is timing-constant when the following parameters are held constant: lowerLimit, upperLimit, bitLength, and endianess. Thus, while the driver may create multiple candidates for the value to find one within the range, timing will not leak the final value's relation to the limits. However, timing may leak the bitLength, the endianess, and the use of CryptoUtils_limitZero, CryptoUtils_limitOne, or NULL for the limit values.

Synopsis

Generate random bytes to a user provided buffer

#include <ti/drivers/RNG.h>
#include "ti_drivers_config.h"
// Setup RNG
RNG_Init();
RNG_fillPoolIfLessThan(RNG_POOL_BYTE_SIZE);
// Use RNG
#define RANDOM_BYTES_SIZE 16u
RNG_Handle handle;
int_fast16_t result;
uint8_t randomBytesArray[RANDOM_BYTES_SIZE] = {0};
handle = RNG_open(0, NULL);
if (!handle) {
    // Handle error
    while(1);
}
result = RNG_getRandomBits(handle, randomBytesArray, RANDOM_BYTES_SIZE * 8);
if (result != RNG_STATUS_SUCCESS) {
    // Handle error
    while(1);
}
RNG_close(handle);
// Refill RNG Pool when convenient
RNG_fillPoolIfLessThan(RNG_POOL_BYTE_SIZE);

Examples

The following examples do not show the process of initializing the RNG module and refilling the pool. See ti_drivers_RNG_Synopsis RNG Driver Synopsis for an example showing those parts of RNG operation. *

Generate a number within a range

#include <ti/drivers/RNG.h>
#define RANDOM_BIT_SIZE  15u
#define RANDOM_BYTE_SIZE ((RANDOM_BIT_SIZE + 7u)/8u)
RNG_Handle handle;
int_fast16_t result;
uint8_t randomBytesArray[RANDOM_BYTES_SIZE] = {0};
uint8_t upperLimit[RANDOM_BYTES_SIZE] = {0xA9, 0x61}; // 25,001, LE format
handle = RNG_open(0, NULL);
if (!handle) {
    // Handle error
    while(1);
}
// Generate a number from 1 to 25,000 (inclusive)
// Note that lowerLimit parameter is inclusive and upperLimit is
// exclusive. Thus, upperLimit is set to 25,001.
result = RNG_getLERandomNumberInRange(RNG_Handle handle, RNG_limitOne,
                                      upperLimit, randomBytesArray,
                                      RANDOM_BIT_SIZE);
if (result != RNG_STATUS_SUCCESS) {
    // Handle error
    while(1);
}
RNG_close(handle);

Generate an ECC private key

#include <ti/drivers/RNG.h>
#include <ti/drivers/cryptoutils/ecc/ECCParams.h>
// Values are chosen to generate a NIST 256 bit key.
CryptoKey privateKey;
uint8_t privateKeyingMaterial[NISTP256_PARAM_SIZE_BYTES];
RNG_Handle handle;
int_fast16_t result;
handle = RNG_open(0, NULL);
if (!handle) {
    // Handle error
    while(1);
}
CryptoKeyPlaintext_initBlankKey(&privateKey, privateKeyingMaterial,
                                ECCParams_NISTP256.length);
// Generate NIST 256 bit key in BE format.
result = RNG_generateBEKeyInRange(RNG_Handle handle, RNG_limitOne,
                                  ECCParams_NISTP256.order, privateKey,
                                  256);
if (result != RNG_STATUS_SUCCESS) {
    // Handle error
    while(1);
}
RNG_close(handle);

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <ti/drivers/cryptoutils/cryptokey/CryptoKey.h>

Include dependency graph for RNG.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	RNG_Config
	RNG Global configuration. More...

struct	RNG_Params
	RNG Parameters. More...

Macros
#define	RNG_STATUS_RESERVED (-32)

#define	RNG_STATUS_SUCCESS ((int_fast16_t)0)
	Successful status code. More...

#define	RNG_STATUS_ERROR ((int_fast16_t)-1)
	Generic error status code. More...

#define	RNG_STATUS_RESOURCE_UNAVAILABLE ((int_fast16_t)-2)
	An error status code returned if the hardware or software resource is currently unavailable. More...

#define	RNG_STATUS_INVALID_INPUTS ((int_fast16_t)-3)
	Operation failed due to invalid inputs. More...

#define	RNG_STATUS_CANCELED ((int_fast16_t)-4)
	The ongoing operation was canceled. More...

#define	RNG_ENTROPY_EXHAUSTED ((int_fast16_t)-5)
	The pool of entropy has been exhausted and additional entropy cannot be generated. A reset of the system may be required to generate more entropy. More...

#define	RNG_STATUS_INIT_NOT_ALLOWED ((int_fast16_t)-6)
	Some implementations have restrictions on how often or when RNG_init may be called. See the documentation for the implementation for more information. More...

#define	RNG_MAX_BIT_LENGTH ((size_t)1u << 20u) /* 1 MiB */
	Maximum number of bits that may be requested in a single call. More...

Typedefs
typedef const RNG_Config *	RNG_Handle
	A handle that is returned from a RNG_open() call. More...

typedef void(*	RNG_CryptoKeyCallbackFxn) (RNG_Handle handle, int_fast16_t returnValue, CryptoKey *key)
	The definition of a callback function used by the RNG driver when RNG_generateKey(), RNG_generateLEKeyInRange(), or RNG_generateBEKeyInRange() is called with RNG_RETURN_BEHAVIOR_CALLBACK. More...

typedef void(*	RNG_RandomBitsCallbackFxn) (RNG_Handle handle, int_fast16_t returnValue, uint8_t *randomBits, size_t randomBitsLength)
	The definition of a callback function used by the RNG driver when RNG_getRandomBits(), RNG_getLERandomNumberInRange(), or RNG_getBERandomNumberInRange is called with RNG_RETURN_BEHAVIOR_CALLBACK. More...

Enumerations
enum	RNG_ReturnBehavior { RNG_RETURN_BEHAVIOR_CALLBACK = 1, RNG_RETURN_BEHAVIOR_BLOCKING = 2, RNG_RETURN_BEHAVIOR_POLLING = 4 }
	The way in which RNG function calls return after generating the requested entropy. More...

Functions
int_fast16_t	RNG_init (void)
	This function initializes the RNG module. More...

int_fast16_t	RNG_fillPoolIfLessThan (size_t bytes)
	Fills the pool with entropy if the number of bytes with entropy in the pool is less than the value specified. More...

void	RNG_Params_init (RNG_Params *params)
	Function to initialize the RNG_Params struct to its defaults. More...

RNG_Handle	RNG_open (uint_least8_t index, const RNG_Params *params)
	This function opens a given RNG peripheral. More...

void	RNG_close (RNG_Handle handle)
	Function to close a RNG peripheral specified by the RNG handle. More...

int_fast16_t	RNG_getRandomBits (RNG_Handle handle, void *randomBits, size_t randomBitsLength)
	Generate random bits and output to the given array. More...

int_fast16_t	RNG_getLERandomNumberInRange (RNG_Handle handle, const void lowerLimit, const void upperLimit, void *randomNumber, size_t randomNumberBitLength)
	Generate random number, stored in little-endian (LE) format, where the number is within the specified range. More...

int_fast16_t	RNG_getBERandomNumberInRange (RNG_Handle handle, const void lowerLimit, const void upperLimit, void *randomNumber, size_t randomNumberBitLength)
	Generate random number, stored in big-endian (BE) format, where the number is within the specified range. More...

int_fast16_t	RNG_generateKey (RNG_Handle handle, CryptoKey *key)
	Generate random bits and output them to the given `CryptoKey` object. More...

int_fast16_t	RNG_generateLEKeyInRange (RNG_Handle handle, const void lowerLimit, const void upperLimit, CryptoKey *key, size_t randomNumberBitLength)
	Generate random number, in little-endian (LE) format, where the number is within the specified range. Store the random number in the given `CryptoKey` object. More...

int_fast16_t	RNG_generateBEKeyInRange (RNG_Handle handle, const void lowerLimit, const void upperLimit, CryptoKey *key, size_t randomNumberBitLength)
	Generate random number, stored in big-endian (BE) format, where the number is within the specified range. Store the random number in the given `CryptoKey` object. More...

RNG_Handle	RNG_construct (const RNG_Config config, const RNG_Params params)
	Constructs a new RNG object. More...

int_fast16_t	RNG_cancelOperation (RNG_Handle handle)
	Aborts an ongoing RNG operation and clears internal buffers. More...

Variables
const RNG_Params	RNG_defaultParams
	Default RNG_Params structure. More...

const size_t	RNG_poolByteSize
	The byte size of the pool. More...

Macro Definition Documentation

§ RNG_STATUS_RESERVED

#define RNG_STATUS_RESERVED (-32)

Common RNG status code reservation offset. RNG driver implementations should offset status codes with RNG_STATUS_RESERVED growing negatively.

Example implementation specific status codes:

#define RNGXYZ_STATUS_ERROR0    ((int_fast16_t) (RNG_STATUS_RESERVED - 0))
#define RNGXYZ_STATUS_ERROR1    ((int_fast16_t) (RNG_STATUS_RESERVED - 1))
#define RNGXYZ_STATUS_ERROR2    ((int_fast16_t) (RNG_STATUS_RESERVED - 2))

§ RNG_STATUS_SUCCESS

#define RNG_STATUS_SUCCESS ((int_fast16_t)0)

Successful status code.

Functions return RNG_STATUS_SUCCESS if the function was executed successfully.

§ RNG_STATUS_ERROR

#define RNG_STATUS_ERROR ((int_fast16_t)-1)

Generic error status code.

Functions return RNG_STATUS_ERROR if the function was not executed successfully.

§ RNG_STATUS_RESOURCE_UNAVAILABLE

#define RNG_STATUS_RESOURCE_UNAVAILABLE ((int_fast16_t)-2)

An error status code returned if the hardware or software resource is currently unavailable.

RNG driver implementations may have hardware or software limitations on how many clients can simultaneously perform operations. This status code is returned if the mutual exclusion mechanism signals that an operation cannot currently be performed.

§ RNG_STATUS_INVALID_INPUTS

#define RNG_STATUS_INVALID_INPUTS ((int_fast16_t)-3)

Operation failed due to invalid inputs.

Functions return RNG_STATUS_INVALID_INPUTS if input validation fails.

§ RNG_STATUS_CANCELED

#define RNG_STATUS_CANCELED ((int_fast16_t)-4)

The ongoing operation was canceled.

§ RNG_ENTROPY_EXHAUSTED

#define RNG_ENTROPY_EXHAUSTED ((int_fast16_t)-5)

The pool of entropy has been exhausted and additional entropy cannot be generated. A reset of the system may be required to generate more entropy.

§ RNG_STATUS_INIT_NOT_ALLOWED

#define RNG_STATUS_INIT_NOT_ALLOWED ((int_fast16_t)-6)

Some implementations have restrictions on how often or when RNG_init may be called. See the documentation for the implementation for more information.

§ RNG_MAX_BIT_LENGTH

#define RNG_MAX_BIT_LENGTH ((size_t)1u << 20u) /* 1 MiB */

Maximum number of bits that may be requested in a single call.

Typedef Documentation

§ RNG_Handle

typedef const RNG_Config* RNG_Handle

A handle that is returned from a RNG_open() call.

§ RNG_CryptoKeyCallbackFxn

typedef void(* RNG_CryptoKeyCallbackFxn) (RNG_Handle handle, int_fast16_t returnValue, CryptoKey *key)

The definition of a callback function used by the RNG driver when RNG_generateKey(), RNG_generateLEKeyInRange(), or RNG_generateBEKeyInRange() is called with RNG_RETURN_BEHAVIOR_CALLBACK.

Warning: Attempting to make calls to the RNG driver from the callback may result in deadlock.

Parameters

handle	Handle of the client that started the RNG operation.
returnValue	Return status code describing the outcome of the operation.
key	The CryptoKey that describes the location the generated entropy will be copied to.

§ RNG_RandomBitsCallbackFxn

typedef void(* RNG_RandomBitsCallbackFxn) (RNG_Handle handle, int_fast16_t returnValue, uint8_t *randomBits, size_t randomBitsLength)

The definition of a callback function used by the RNG driver when RNG_getRandomBits(), RNG_getLERandomNumberInRange(), or RNG_getBERandomNumberInRange is called with RNG_RETURN_BEHAVIOR_CALLBACK.

Warning: Attempting to make calls to the RNG driver from the callback may result in deadlock.

Parameters

handle	Handle of the client that started the RNG operation.
returnValue	Return status code describing the outcome of the operation.
randomBits	Pointer to an array that stores the random bits output by this function.
randomBitsLength	The length of the random data generated, in bits.

Enumeration Type Documentation

§ RNG_ReturnBehavior

enum RNG_ReturnBehavior

The way in which RNG function calls return after generating the requested entropy.

Not all RNG implementations support all of the return behavior options.

Not all RNG operations exhibit the specified return behavior. Functions that do not require significant computation and cannot offload that computation to a background thread behave like regular functions. Which functions exhibit the specified return behavior is not implementation dependent. Specifically, a software-backed implementation run on the same CPU as the application will emulate the return behavior while not actually offloading the computation to the background thread.

RNG functions exhibiting the specified return behavior have restrictions on the context from which they may be called.

	Task	Hwi	Swi
RNG_RETURN_BEHAVIOR_CALLBACK	X
RNG_RETURN_BEHAVIOR_BLOCKING	X
RNG_RETURN_BEHAVIOR_POLLING	X	X	X

Enumerator
RNG_RETURN_BEHAVIOR_CALLBACK	The function call will return immediately while the RNG operation goes on in the background. The registered callback function is called after the operation completes. The context the callback function is called (task, HWI, SWI) is implementation-dependent.
RNG_RETURN_BEHAVIOR_BLOCKING	The function call will block while RNG operation goes on in the background. RNG operation results are available after the function returns.
RNG_RETURN_BEHAVIOR_POLLING	The function call will continuously poll a flag while RNG operation goes on in the background. RNG operation results are available after the function returns.

Function Documentation

§ RNG_init()

int_fast16_t RNG_init ( void )

This function initializes the RNG module.

Precondition: The RNG_config structure must exist and be persistent before this function can be called. This function must also be called before any other RNG driver APIs. This function call does not modify any peripheral registers.

Return values

RNG_STATUS_SUCCESS	The operation succeeded.
RNG_STATUS_ERROR	The operation failed.
RNG_STATUS_RESOURCE_UNAVAILABLE	The required hardware resource was not available. Try again later.

§ RNG_fillPoolIfLessThan()

int_fast16_t RNG_fillPoolIfLessThan ( size_t bytes )

Fills the pool with entropy if the number of bytes with entropy in the pool is less than the value specified.

Note: This function does not take in a handle and the implementation may run in either blocking or polling mode.

Precondition: RNG_init() has to be called first.

Parameters

bytes Pool will be filled if current level is less than this number. Use RNG_POOL_BYTE_SIZE (from ti_drivers_config.h) to always fill.

Return values

RNG_STATUS_SUCCESS	The operation succeeded.
RNG_STATUS_ERROR	The operation failed.
RNG_STATUS_RESOURCE_UNAVAILABLE	The required hardware resource was not available. Try again later.
RNG_ENTROPY_EXHAUSTED	Pool could not be refilled, device may need reset.

§ RNG_Params_init()

void RNG_Params_init ( RNG_Params * params )

Function to initialize the RNG_Params struct to its defaults.

Parameters

params An pointer to RNG_Params structure for initialization

Default values are:
returnBehavior = RNG_RETURN_BEHAVIOR_BLOCKING
cryptoKeyCallbackFxn = NULL
randomBitsCallbackFxn = NULL
timeout = SemaphoreP_WAIT_FOREVER
custom = NULL

§ RNG_open()

RNG_Handle RNG_open	(	uint_least8_t	index,
		const RNG_Params *	params
	)

This function opens a given RNG peripheral.

Precondition: RNG controller has been initialized using RNG_init()

Parameters

index	Logical peripheral number for the RNG indexed into the RNG_config table
params	Pointer to an parameter block, if NULL it will use default values.

Returns: A RNG_Handle on success or a NULL on an error or if it has been opened already.

See also: RNG_init(); RNG_close()

§ RNG_close()

void RNG_close ( RNG_Handle handle )

Function to close a RNG peripheral specified by the RNG handle.

Precondition: RNG_open() has to be called first.

Parameters

handle A RNG handle returned from RNG_open()

See also: RNG_open()

§ RNG_getRandomBits()

int_fast16_t RNG_getRandomBits	(	RNG_Handle	handle,
		void *	randomBits,
		size_t	randomBitsLength
	)

Generate random bits and output to the given array.

Generates random a random number of bits with length of randomBitsLength. The output length in bytes will be the minimum number of bytes needed to contain randomBitsLength. The output will be placed at the address pointed to by randomBits. The user shall be responsible for allocating sufficient memory starting at the address pointed at by randomBits to hold the number of bytes output.

Attention: When called with RNG_RETURN_BEHAVIOR_CALLBACK, provide a callback function of type RNG_RandomBitsCallbackFxn.

Note: See RNG_generateKey() to output random bytes to a CryptoKey instead.

Precondition: RNG_open() has to be called first.

Parameters

handle	A RNG handle returned from RNG_open().
randomBits	Pointer to an array that stores the random bits output by this function.
randomBitsLength	The length of the random data required, in bits. A maximum of 1MiB is allowed.

See also: RNG_getLERandomNumberInRange; RNG_getBERandomNumberInRange

Return values

RNG_STATUS_SUCCESS	The operation succeeded.
RNG_STATUS_ERROR	The operation failed.
RNG_STATUS_RESOURCE_UNAVAILABLE	The required hardware resource was not available. Try again later.
RNG_STATUS_INVALID_INPUTS	Inputs provided are not valid.
RNG_ENTROPY_EXHAUSTED	Requested number of bytes could not be obtained. Device may need reset.

§ RNG_getLERandomNumberInRange()

int_fast16_t RNG_getLERandomNumberInRange	(	RNG_Handle	handle,
		const void *	lowerLimit,
		const void *	upperLimit,
		void *	randomNumber,
		size_t	randomNumberBitLength
	)

Generate random number, stored in little-endian (LE) format, where the number is within the specified range.

Generates random a random number within the range [lowerLimit, upperLimit) of bit size randomNumberBitLength. The output length in bytes will be the minimum number of bytes needed to contain randomNumberBitLength. The output will be placed at the address pointed to by randomNumber. The user shall be responsible for allocating sufficient memory starting at the address pointed at by randomNumber to hold the number of bytes output.

Note that the special values of CryptoUtils_limitZero and CryptoUtils_limitOne are available to pass in for the lowerLimit. (These values can also be used for the upperLimit but their use for the upperLimit has no practical use.)

If lowerLimit is NULL then the lower limit is taken as 0. If upperLimit is NULL then the upper limit is taken as 2^{(bitLength + 1)}.

Attention: When called with RNG_RETURN_BEHAVIOR_CALLBACK, provide a callback function of type RNG_RandomBitsCallbackFxn.

Note: See RNG_generateLEKeyInRange() to output a ranged number to a CryptoKey instead.

Precondition: RNG_open() has to be called first.

Parameters

handle	A RNG handle returned from RNG_open().
lowerLimit	Pointer to an array that stores the lower limit (inclusive) in LE format for the generated number.
upperLimit	Pointer to an array that stores the upper limit (exclusive) in LE format for the generated number.
randomNumber	Pointer to an array that stores the random number output by this function.
randomNumberBitLength	The length, in bits, of both the limit values and the random number to be generated.

See also: CryptoUtils_limitZero; CryptoUtils_limitOne

Return values

RNG_STATUS_SUCCESS	The operation succeeded.
RNG_STATUS_ERROR	The operation failed.
RNG_STATUS_RESOURCE_UNAVAILABLE	The required hardware resource was not available. Try again later.
RNG_STATUS_INVALID_INPUTS	Inputs provided are not valid.
RNG_ENTROPY_EXHAUSTED	Requested number of bytes could not be obtained. Device may need reset.

§ RNG_getBERandomNumberInRange()

int_fast16_t RNG_getBERandomNumberInRange	(	RNG_Handle	handle,
		const void *	lowerLimit,
		const void *	upperLimit,
		void *	randomNumber,
		size_t	randomNumberBitLength
	)

Generate random number, stored in big-endian (BE) format, where the number is within the specified range.

Generates random a random number within the range [lowerLimit, upperLimit) of bit size randomNumberBitLength. The output length in bytes will be the minimum number of bytes needed to contain randomNumberBitLength. The output will be placed at the address pointed to by randomNumber. The user shall be responsible for allocating sufficient memory starting at the address pointed at by randomNumber to hold the number of bytes output.

Note that the special values of CryptoUtils_limitZero and CryptoUtils_limitOne are available to pass in for the lowerLimit. (These values can also be used for the upperLimit but their use for the upperLimit has no practical use.)

If lowerLimit is NULL then the lower limit is taken as 0. If upperLimit is NULL then the upper limit is taken as 2^{(bitLength + 1)}.

Attention: When called with RNG_RETURN_BEHAVIOR_CALLBACK, provide a callback function of type RNG_RandomBitsCallbackFxn.

Note: See RNG_generateBEKeyInRange() to output a ranged number to a CryptoKey instead.

Precondition: RNG_open() has to be called first.

Parameters

handle	A RNG handle returned from RNG_open().
lowerLimit	Pointer to an array that stores the lower limit (inclusive) in BE format for the generated number.
upperLimit	Pointer to an array that stores the upper limit (exclusive) in BE format for the generated number.
randomNumber	Pointer to an array that stores the random number output by this function.
randomNumberBitLength	The length, in bits, of both the limit value and the random number to be generated.

See also: CryptoUtils_limitZero; CryptoUtils_limitOne

Return values

RNG_STATUS_SUCCESS	The operation succeeded.
RNG_STATUS_ERROR	The operation failed.
RNG_STATUS_RESOURCE_UNAVAILABLE	The required hardware resource was not available. Try again later.
RNG_STATUS_INVALID_INPUTS	Inputs provided are not valid.
RNG_ENTROPY_EXHAUSTED	Requested number of bytes could not be obtained. Device may need reset.

§ RNG_generateKey()

int_fast16_t RNG_generateKey	(	RNG_Handle	handle,
		CryptoKey *	key
	)

Generate random bits and output them to the given CryptoKey object.

Generates a random bitstream of the size defined in the key CryptoKey in the range 0 <= key buffer < 2 ^ (entropy length * 8). The entropy will be generated and stored according to the storage requirements defined in the CryptoKey. The length of the entropy generated will be the same as the key length.

Attention: When called with RNG_RETURN_BEHAVIOR_CALLBACK, provide a callback function of type RNG_CryptoKeyCallbackFxn.

Precondition: RNG_open() has to be called first.

Parameters

handle	A RNG handle returned from RNG_open().
key	Pointer to a blank CryptoKey, initialized with a length and appropriate storage for storing a key of the specified length.

See also: RNG_generateLEKeyInRange; RNG_generateBEKeyInRange

Return values

RNG_STATUS_SUCCESS	The operation succeeded.
RNG_STATUS_ERROR	The operation failed.
RNG_STATUS_RESOURCE_UNAVAILABLE	The required hardware resource was not available. Try again later.
RNG_STATUS_INVALID_INPUTS	Inputs provided are not valid.
RNG_ENTROPY_EXHAUSTED	Requested number of bytes could not be obtained. Device may need reset.

§ RNG_generateLEKeyInRange()

int_fast16_t RNG_generateLEKeyInRange	(	RNG_Handle	handle,
		const void *	lowerLimit,
		const void *	upperLimit,
		CryptoKey *	key,
		size_t	randomNumberBitLength
	)

Generate random number, in little-endian (LE) format, where the number is within the specified range. Store the random number in the given CryptoKey object.

Generates a random number within the range [lowerLimit, upperLimit) of bit size randomNumberBitLength. The output length in bytes will be the minimum number of bytes needed to contain randomNumberBitLength. The output will be placed as specified by the members of key.

Note that the special values of CryptoUtils_limitZero and CryptoUtils_limitOne are available to pass in for the lowerLimit. (These values can also be used for the upperLimit but their use for the upperLimit has no practical use.)

If lowerLimit is NULL then the lower limit is taken as 0. If upperLimit is NULL then the upper limit is taken as 2^{(bitLength + 1)}.

Attention: When called with RNG_RETURN_BEHAVIOR_CALLBACK, provide a callback function of type RNG_CryptoKeyCallbackFxn.

Precondition: RNG_open() has to be called first.

Parameters

handle	A RNG handle returned from RNG_open().
lowerLimit	Pointer to an array that stores the lower limit (inclusive) in LE format for the generated number.
upperLimit	Pointer to an array that stores the upper limit (exclusive) in LE format for the generated number.
key	Pointer to a blank CryptoKey, initialized with a length and appropriate storage for storing a key of the specified length.
randomNumberBitLength	The length, in bits, of both the limit values and the random number to be generated.

See also: CryptoUtils_limitZero; CryptoUtils_limitOne

Return values

RNG_STATUS_SUCCESS	The operation succeeded.
RNG_STATUS_ERROR	The operation failed.
RNG_STATUS_RESOURCE_UNAVAILABLE	The required hardware resource was not available. Try again later.
RNG_STATUS_INVALID_INPUTS	Inputs provided are not valid.
RNG_ENTROPY_EXHAUSTED	Requested number of bytes could not be obtained. Device may need reset.

§ RNG_generateBEKeyInRange()

int_fast16_t RNG_generateBEKeyInRange	(	RNG_Handle	handle,
		const void *	lowerLimit,
		const void *	upperLimit,
		CryptoKey *	key,
		size_t	randomNumberBitLength
	)

Generate random number, stored in big-endian (BE) format, where the number is within the specified range. Store the random number in the given CryptoKey object.

Generates a random number within the range [lowerLimit, upperLimit) of bit size randomNumberBitLength. The output length in bytes will be the minimum number of bytes needed to contain randomNumberBitLength. The output will be placed as specified by the members of key.

Note that the special values of CryptoUtils_limitZero and CryptoUtils_limitOne are available to pass in for the lowerLimit. (These values can also be used for the upperLimit but their use for the upperLimit has no practical use.)

If lowerLimit is NULL then the lower limit is taken as 0. If upperLimit is NULL then the upper limit is taken as 2^{(bitLength + 1)}.

Attention: When called with RNG_RETURN_BEHAVIOR_CALLBACK, provide a callback function of type RNG_CryptoKeyCallbackFxn.

Precondition: RNG_open() has to be called first.

Parameters

handle	A RNG handle returned from RNG_open().
lowerLimit	Pointer to an array that stores the lower limit (inclusive) in BE format for the generated number.
upperLimit	Pointer to an array that stores the upper limit (exclusive) in BE format for the generated number.
key	Pointer to a blank CryptoKey, initialized with a length and appropriate storage for storing a key of the specified length.
randomNumberBitLength	The length, in bits, of both the limit values and the random number to be generated.

See also: CryptoUtils_limitZero; CryptoUtils_limitOne

Return values

RNG_STATUS_SUCCESS	The operation succeeded.
RNG_STATUS_ERROR	The operation failed.
RNG_STATUS_RESOURCE_UNAVAILABLE	The required hardware resource was not available. Try again later.
RNG_STATUS_INVALID_INPUTS	Inputs provided are not valid.
RNG_ENTROPY_EXHAUSTED	Requested number of bytes could not be obtained. Device may need reset.

§ RNG_construct()

RNG_Handle RNG_construct	(	const RNG_Config *	config,
		const RNG_Params *	params
	)

Constructs a new RNG object.

Unlike RNG_open(), RNG_construct() does not require the hwAttrs and object to be allocated in a RNG_Config array that is indexed into. Instead, the RNG_Config, hwAttrs, and object can be allocated at any location. This allows for relatively simple run-time allocation of temporary driver instances on the stack or the heap. The drawback is that this makes it more difficult to write device-agnostic code. If you use an ifdef with DeviceFamily, you can choose the correct object and hwAttrs to allocate. That compilation unit will be tied to the device it was compiled for at this point. To change devices, recompilation of the application with a different DeviceFamily setting is necessary.

Parameters

config	RNG_Config describing the location of the object and hwAttrs.
params	RNG_Params to configure the driver instance.

Returns: Returns a RNG_Handle on success or NULL on failure.

Precondition: The object struct config points to must be zeroed out prior to calling this function. Otherwise, unexpected behavior may ensue.

§ RNG_cancelOperation()

int_fast16_t RNG_cancelOperation ( RNG_Handle handle )

Aborts an ongoing RNG operation and clears internal buffers.

Aborts an operation to generate random bytes/entropy. The operation will terminate as though an error occurred and the status code of the operation will be RNG_STATUS_CANCELED in this case.

Any entropy already copied out of the pool will have already been removed from the pool and will not be reused for later requests.

Canceling an operation may be delayed if the entropy pool is below its minimum fill mark as the driver will refill the pool before finishing the cancelled operation.

Parameters

handle A RNG_Handle returned from RNG_open()

Return values

RNG_STATUS_SUCCESS The operation was canceled or there was no operation in progress to be canceled.

Variable Documentation

§ RNG_defaultParams

const RNG_Params RNG_defaultParams

Default RNG_Params structure.

See also: RNG_Params_init()

§ RNG_poolByteSize

const size_t RNG_poolByteSize

The byte size of the pool.

Detailed Description

Overview

Usage

Initialization

Before starting a RNG operation

Entropy Pool Management

RNG operations

After the RNG operation completes

Security

Data Protection

Timing Side Channels

Synopsis

Generate random bytes to a user provided buffer

Examples

Generate a number within a range

Generate an ECC private key

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Macro Definition Documentation

§ RNG_STATUS_RESERVED

§ RNG_STATUS_SUCCESS

§ RNG_STATUS_ERROR

§ RNG_STATUS_RESOURCE_UNAVAILABLE

§ RNG_STATUS_INVALID_INPUTS

§ RNG_STATUS_CANCELED

§ RNG_ENTROPY_EXHAUSTED

§ RNG_STATUS_INIT_NOT_ALLOWED

§ RNG_MAX_BIT_LENGTH

Typedef Documentation

§ RNG_Handle

§ RNG_CryptoKeyCallbackFxn

§ RNG_RandomBitsCallbackFxn

Enumeration Type Documentation

§ RNG_ReturnBehavior

Function Documentation

§ RNG_init()

§ RNG_fillPoolIfLessThan()

§ RNG_Params_init()

§ RNG_open()

§ RNG_close()

§ RNG_getRandomBits()

§ RNG_getLERandomNumberInRange()

§ RNG_getBERandomNumberInRange()

§ RNG_generateKey()

§ RNG_generateLEKeyInRange()

§ RNG_generateBEKeyInRange()

§ RNG_construct()

§ RNG_cancelOperation()

Variable Documentation

§ RNG_defaultParams

§ RNG_poolByteSize