Detailed Description

TRNG driver header.

Overview

The True Random Number Generator (TRNG) module generates random data of variable lengths from a source of entropy. The output is suitable for applications requiring cryptographically random data such as keying material for private or symmetric keys.

Usage

Before starting a TRNG operation

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

Call TRNG_init() to initialize the driver.
Call TRNG_Params_init() to initialize the TRNG_Params to default values.
Modify the TRNG_Params as desired.
Call TRNG_open() to open an instance of the driver.
Option 1: Use TRNG_generateKey() that writes random bytes to a CryptoKey.
Initialize a blank CryptoKey. These opaque data structures are representations of keying material and its storage. Depending on how the keying material is stored (RAM or flash, key store), the CryptoKey must be initialized differently. The TRNG API can handle all types of CryptoKey. However, not all device-specific implementations support all types of CryptoKey. Devices without a key store will not support CryptoKeys with keying material stored in a key store for example. All devices support plaintext CryptoKeys.
Option 2: Use TRNG_getRandomBytes() that writes random bytes to a buffer.
Allocate memory sufficient to hold the number of bytes of random data requested.

TRNG operations

TRNG_generateKey() provides the most basic functionality. Use it to generate key-material of a specified size. An example use-case would be generating a symmetric key for AES encryption and / or authentication. If entropy data is needed for anything other than a key-material, use TRNG_getRandomBytes() that writes random bytes from the entropy source to a buffer/array.

To generate an ECC private key, you should use rejection sampling to ensure that the keying material is in the interval [1, n - 1]. The ECDH public key generation APIs will reject private keys that are outside of this interval. This information may be used to generate keying material until a suitable key is generated. For most curves, it is improbable to generate a random number outside of this interval because n is a large number close to the maximum number that would fit in the k-byte keying material array. An example of how to do this is given below.

After the TRNG operation completes

After the TRNG operation completes, the application should either start another operation or close the driver by calling TRNG_close().

Synopsis

// Import TRNG Driver definitions
#include <ti/drivers/TRNG.h>
#include <ti/drivers/cryptoutils/cryptokey/CryptoKeyPlaintext.h>
// Define name for TRNG channel index
#define TRNG_INSTANCE 0
#define KEY_LENGTH_BYTES 16
TRNG_init();
handle = TRNG_open(TRNG_INSTANCE, NULL);
CryptoKeyPlaintext_initBlankKey(&entropyKey, entropyBuffer, KEY_LENGTH_BYTES);
result = TRNG_generateKey(handle, &entropyKey);
TRNG_close(handle);

Examples

Generate symmetric encryption key

#include <ti/drivers/TRNG.h>
#include <ti/drivers/cryptoutils/cryptokey/CryptoKeyPlaintext.h>
#define KEY_LENGTH_BYTES 16
TRNG_Handle handle;
int_fast16_t result;
CryptoKey entropyKey;
uint8_t entropyBuffer[KEY_LENGTH_BYTES] = {0};
handle = TRNG_open(0, NULL);
if (!handle) {
    // Handle error
    while(1);
}
CryptoKeyPlaintext_initBlankKey(&entropyKey, entropyBuffer, KEY_LENGTH_BYTES);
result = TRNG_generateKey(handle, &entropyKey);
if (result != TRNG_STATUS_SUCCESS) {
    // Handle error
    while(1);
}
TRNG_close(handle);

Generate ECC private and public key using rejection sampling

#include <ti/drivers/TRNG.h>
#include <ti/drivers/ECDH.h>
#include <ti/drivers/cryptoutils/cryptokey/CryptoKeyPlaintext.h>
#include <ti/drivers/cryptoutils/ecc/ECCParams.h>
TRNG_Handle trngHandle;
ECDH_Handle ecdhHandle;
CryptoKey privateKey;
CryptoKey publicKey;
int_fast16_t trngResult;
int_fast16_t ecdhResult;
uint8_t privateKeyingMaterial[32];
uint8_t publicKeyingMaterial[64];
ECDH_OperationGeneratePublicKey genPubKeyOperation;
trngHandle = TRNG_open(0, NULL);
if (!trngHandle) {
    while(1);
}
ecdhHandle = ECDH_open(0, NULL);
if (!ecdhHandle) {
    while(1);
}
// Repeatedly generate random numbers until they are in the range [1, n - 1].
// Since the NIST-P256 order is so close to 2^256, the probability of needing
// to generate more than one random number is incredibly low but not non-zero.
do {
    CryptoKeyPlaintext_initBlankKey(&privateKey, privateKeyingMaterial, ECCParams_NISTP256.length);
    CryptoKeyPlaintext_initBlankKey(&publicKey, publicKeyingMaterial, 2 * ECCParams_NISTP256.length);
    trngResult = TRNG_generateKey(trngHandle, &privateKey);
    if (trngResult != TRNG_STATUS_SUCCESS) {
        while(1);
    }
    ECDH_OperationGeneratePublicKey_init(&genPubKeyOperation);
    genPubKeyOperation.curve = &ECCParams_NISTP256;
    genPubKeyOperation.myPrivateKey = &privateKey;
    genPubKeyOperation.myPublicKey = &publicKey;
    ecdhResult = ECDH_generatePublicKey(ecdhHandle, &genPubKeyOperation);
} while(ecdhResult == ECDH_STATUS_PRIVATE_KEY_LARGER_EQUAL_ORDER || ecdhResult == ECDH_STATUS_PRIVATE_KEY_ZERO);
TRNG_close(trngHandle);
ECDH_close(ecdhHandle);

Generate random bytes to a user provided buffer

#include <ti/drivers/TRNG.h>
#define RANDOM_BYTES_SIZE 16
TRNG_Handle handle;
int_fast16_t result;
uint8_t randomBytesArray[RANDOM_BYTES_SIZE] = {0};
handle = TRNG_open(0, NULL);
if (!handle) {
    // Handle error
    while(1);
}
result = TRNG_getRandomBytes(handle, randomBytesArray, RANDOM_BYTES_SIZE);
if (result != TRNG_STATUS_SUCCESS) {
    // Handle error
    while(1);
}
TRNG_close(handle);

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

Include dependency graph for TRNG.h:

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

Go to the source code of this file.

Data Structures
struct	TRNG_Config
	TRNG Global configuration. More...

struct	TRNG_Params
	TRNG Parameters. More...

Macros
#define	TRNG_STATUS_RESERVED (-32)

#define	TRNG_STATUS_SUCCESS (0)
	Successful status code. More...

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

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

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

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

Typedefs
typedef TRNG_Config *	TRNG_Handle
	A handle that is returned from a TRNG_open() call. More...

typedef void(*	TRNG_CryptoKeyCallbackFxn) (TRNG_Handle handle, int_fast16_t returnValue, CryptoKey *entropy)
	The definition of a callback function used by the TRNG driver when TRNG_generateKey() is called with TRNG_RETURN_BEHAVIOR_CALLBACK. More...

typedef void(*	TRNG_RandomBytesCallbackFxn) (TRNG_Handle handle, int_fast16_t returnValue, uint8_t *randomBytes, size_t randomBytesSize)
	The definition of a callback function used by the TRNG driver when TRNG_getRandomBytes() is called with TRNG_RETURN_BEHAVIOR_CALLBACK. More...

typedef TRNG_CryptoKeyCallbackFxn	TRNG_CallbackFxn
	The definition of a callback function used by the TRNG driver when used in TRNG_RETURN_BEHAVIOR_CALLBACK. More...

Enumerations
enum	TRNG_ReturnBehavior { TRNG_RETURN_BEHAVIOR_CALLBACK = 1, TRNG_RETURN_BEHAVIOR_BLOCKING = 2, TRNG_RETURN_BEHAVIOR_POLLING = 4 }
	The way in which TRNG function calls return after generating the requested entropy. More...

Functions
void	TRNG_init (void)
	This function initializes the TRNG module. More...

void	TRNG_Params_init (TRNG_Params *params)
	Function to initialize the TRNG_Params struct to its defaults. More...

TRNG_Handle	TRNG_open (uint_least8_t index, TRNG_Params *params)
	This function opens a given TRNG peripheral. More...

void	TRNG_close (TRNG_Handle handle)
	Function to close a TRNG peripheral specified by the TRNG handle. More...

int_fast16_t	TRNG_generateEntropy (TRNG_Handle handle, CryptoKey *entropy)
	Generate random bytes and output to the given `CryptoKey` object. More...

int_fast16_t	TRNG_generateKey (TRNG_Handle handle, CryptoKey *entropy)
	Generate random bytes and output to the given `CryptoKey` object. More...

int_fast16_t	TRNG_getRandomBytes (TRNG_Handle handle, void *randomBytes, size_t randomBytesSize)
	Generate random bytes and output to the given array. More...

TRNG_Handle	TRNG_construct (TRNG_Config config, const TRNG_Params params)
	Constructs a new TRNG object. More...

int_fast16_t	TRNG_cancelOperation (TRNG_Handle handle)
	Aborts an ongoing TRNG operation and clears internal buffers. More...

Variables
const TRNG_Params	TRNG_defaultParams
	Default TRNG_Params structure. More...

Macro Definition Documentation

§ TRNG_STATUS_RESERVED

#define TRNG_STATUS_RESERVED (-32)

Common TRNG status code reservation offset. TRNG driver implementations should offset status codes with TRNG_STATUS_RESERVED growing negatively.

Example implementation specific status codes:

#define TRNGXYZ_STATUS_ERROR0    TRNG_STATUS_RESERVED - 0
#define TRNGXYZ_STATUS_ERROR1    TRNG_STATUS_RESERVED - 1
#define TRNGXYZ_STATUS_ERROR2    TRNG_STATUS_RESERVED - 2

§ TRNG_STATUS_SUCCESS

#define TRNG_STATUS_SUCCESS (0)

Successful status code.

Functions return TRNG_STATUS_SUCCESS if the function was executed successfully.

§ TRNG_STATUS_ERROR

#define TRNG_STATUS_ERROR (-1)

Generic error status code.

Functions return TRNG_STATUS_ERROR if the function was not executed successfully.

§ TRNG_STATUS_RESOURCE_UNAVAILABLE

#define TRNG_STATUS_RESOURCE_UNAVAILABLE (-2)

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

TRNG 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.

§ TRNG_STATUS_INVALID_INPUTS

#define TRNG_STATUS_INVALID_INPUTS (-3)

Operation failed due to invalid inputs.

Functions return TRNG_STATUS_INVALID_INPUTS if input validation fails.

§ TRNG_STATUS_CANCELED

#define TRNG_STATUS_CANCELED (-4)

The ongoing operation was canceled.

Typedef Documentation

§ TRNG_Handle

typedef TRNG_Config* TRNG_Handle

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

§ TRNG_CryptoKeyCallbackFxn

typedef void(* TRNG_CryptoKeyCallbackFxn) (TRNG_Handle handle, int_fast16_t returnValue, CryptoKey *entropy)

The definition of a callback function used by the TRNG driver when TRNG_generateKey() is called with TRNG_RETURN_BEHAVIOR_CALLBACK.

Attention: This will replace TRNG_CallbackFxn, which is currently deprecated.

Parameters

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

§ TRNG_RandomBytesCallbackFxn

typedef void(* TRNG_RandomBytesCallbackFxn) (TRNG_Handle handle, int_fast16_t returnValue, uint8_t *randomBytes, size_t randomBytesSize)

The definition of a callback function used by the TRNG driver when TRNG_getRandomBytes() is called with TRNG_RETURN_BEHAVIOR_CALLBACK.

Parameters

handle	Handle of the client that started the TRNG operation.
returnValue	Return status code describing the outcome of the operation.
randomBytes	Pointer to an array that stores the random bytes output by this function.
randomBytesSize	The size of the random data required.

§ TRNG_CallbackFxn

typedef TRNG_CryptoKeyCallbackFxn TRNG_CallbackFxn

The definition of a callback function used by the TRNG driver when used in TRNG_RETURN_BEHAVIOR_CALLBACK.

Deprecated:: TRNG_CallbackFxn will be replaced by TRNG_CryptoKeyCallbackFxn

Enumeration Type Documentation

§ TRNG_ReturnBehavior

enum TRNG_ReturnBehavior

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

Not all TRNG 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.

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

	Task	Hwi	Swi
TRNG_RETURN_BEHAVIOR_CALLBACK	X	X	X
TRNG_RETURN_BEHAVIOR_BLOCKING	X
TRNG_RETURN_BEHAVIOR_POLLING	X	X	X

Enumerator
TRNG_RETURN_BEHAVIOR_CALLBACK	The function call will return immediately while the TRNG 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.
TRNG_RETURN_BEHAVIOR_BLOCKING	The function call will block while TRNG operation goes on in the background. TRNG operation results are available after the function returns.
TRNG_RETURN_BEHAVIOR_POLLING	The function call will continuously poll a flag while TRNG operation goes on in the background. TRNG operation results are available after the function returns.

Function Documentation

§ TRNG_init()

void TRNG_init ( void )

This function initializes the TRNG module.

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

§ TRNG_Params_init()

void TRNG_Params_init ( TRNG_Params * params )

Function to initialize the TRNG_Params struct to its defaults.

Parameters

params An pointer to TRNG_Params structure for initialization

Default values are:
returnBehavior = TRNG_RETURN_BEHAVIOR_BLOCKING
cryptoKeyCallbackFxn = NULL
randomBytesCallbackFxn = NULL
timeout = SemaphoreP_WAIT_FOREVER
custom = NULL

§ TRNG_open()

TRNG_Handle TRNG_open	(	uint_least8_t	index,
		TRNG_Params *	params
	)

This function opens a given TRNG peripheral.

Precondition: TRNG controller has been initialized using TRNG_init()

Parameters

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

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

See also: TRNG_init(); TRNG_close()

§ TRNG_close()

void TRNG_close ( TRNG_Handle handle )

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

Precondition: TRNG_open() has to be called first.

Parameters

handle A TRNG handle returned from TRNG_open()

See also: TRNG_open()

§ TRNG_generateEntropy()

int_fast16_t TRNG_generateEntropy	(	TRNG_Handle	handle,
		CryptoKey *	entropy
	)

Generate random bytes and output to the given CryptoKey object.

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

Deprecated:: This function has been replaced by a pair of new functions. See TRNG_generateKey() and TRNG_getRandomBytes().

Precondition: TRNG_open() has to be called first.

Parameters

handle	A TRNG handle returned from TRNG_open().
entropy	Pointer to a `CryptoKey` object that should already be initialized to hold a plaintext key, provided with the length and the address of the plaintext key-material where the generated entropy will be populated.

Return values

TRNG_STATUS_SUCCESS	The operation succeeded.
TRNG_STATUS_ERROR	The operation failed.
TRNG_STATUS_RESOURCE_UNAVAILABLE	The required hardware resource was not available. Try again later.
TRNG_STATUS_INVALID_INPUTS	Inputs provided are not valid.

§ TRNG_generateKey()

int_fast16_t TRNG_generateKey	(	TRNG_Handle	handle,
		CryptoKey *	entropy
	)

Generate random bytes and output to the given CryptoKey object.

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

Note: This function replaces TRNG_generateEntropy(). See TRNG_getRandomBytes() to output random bytes to an array instead.

Attention: When called with TRNG_RETURN_BEHAVIOR_CALLBACK, provide a callback function of type TRNG_CryptoKeyCallbackFxn.

Precondition: TRNG_open() has to be called first.

Parameters

handle	A TRNG handle returned from TRNG_open().
entropy	Pointer to a `CryptoKey` object that should already be initialized to hold a plaintext key, provided with the length and the address of the plaintext key-material where the generated entropy will be populated.

Return values

TRNG_STATUS_SUCCESS	The operation succeeded.
TRNG_STATUS_ERROR	The operation failed.
TRNG_STATUS_RESOURCE_UNAVAILABLE	The required hardware resource was not available. Try again later.
TRNG_STATUS_INVALID_INPUTS	Inputs provided are not valid.

§ TRNG_getRandomBytes()

int_fast16_t TRNG_getRandomBytes	(	TRNG_Handle	handle,
		void *	randomBytes,
		size_t	randomBytesSize
	)

Generate random bytes and output to the given array.

Generates random bytes of size given by randomBytesSize and stores it in the array pointed at by randomBytes. The user shall be responsible for allocating randomBytesSize long memory starting at the address pointed at by randomBytes.

Attention: When called with TRNG_RETURN_BEHAVIOR_CALLBACK, provide a callback function of type TRNG_RandomBytesCallbackFxn.

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

Precondition: TRNG_open() has to be called first.

Parameters

handle	A TRNG handle returned from TRNG_open().
randomBytes	Pointer to an array that stores the random bytes output by this function.
randomBytesSize	The size of the random data required.

Return values

TRNG_STATUS_SUCCESS	The operation succeeded.
TRNG_STATUS_ERROR	The operation failed.
TRNG_STATUS_RESOURCE_UNAVAILABLE	The required hardware resource was not available. Try again later.
TRNG_STATUS_INVALID_INPUTS	Inputs provided are not valid.

§ TRNG_construct()

TRNG_Handle TRNG_construct	(	TRNG_Config *	config,
		const TRNG_Params *	params
	)

Constructs a new TRNG object.

Unlike TRNG_open(), TRNG_construct() does not require the hwAttrs and object to be allocated in a TRNG_Config array that is indexed into. Instead, the TRNG_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	TRNG_Config describing the location of the object and hwAttrs.
params	TRNG_Params to configure the driver instance.

Returns: Returns a TRNG_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.

§ TRNG_cancelOperation()

int_fast16_t TRNG_cancelOperation ( TRNG_Handle handle )

Aborts an ongoing TRNG 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 TRNG_STATUS_CANCELED in this case.

Parameters

handle A TRNG_Handle returned from TRNG_open()

Return values

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

Variable Documentation

§ TRNG_defaultParams

const TRNG_Params TRNG_defaultParams

Default TRNG_Params structure.

See also: TRNG_Params_init()

Detailed Description

Overview

Usage

Before starting a TRNG operation

TRNG operations

After the TRNG operation completes

Synopsis

Examples

Generate symmetric encryption key

Generate ECC private and public key using rejection sampling

Generate random bytes to a user provided buffer

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Macro Definition Documentation

§ TRNG_STATUS_RESERVED

§ TRNG_STATUS_SUCCESS

§ TRNG_STATUS_ERROR

§ TRNG_STATUS_RESOURCE_UNAVAILABLE

§ TRNG_STATUS_INVALID_INPUTS

§ TRNG_STATUS_CANCELED

Typedef Documentation

§ TRNG_Handle

§ TRNG_CryptoKeyCallbackFxn

§ TRNG_RandomBytesCallbackFxn

§ TRNG_CallbackFxn

Enumeration Type Documentation

§ TRNG_ReturnBehavior

Function Documentation

§ TRNG_init()

§ TRNG_Params_init()

§ TRNG_open()

§ TRNG_close()

§ TRNG_generateEntropy()

§ TRNG_generateKey()

§ TRNG_getRandomBytes()

§ TRNG_construct()

§ TRNG_cancelOperation()

Variable Documentation

§ TRNG_defaultParams