Detailed Description

TRNG driver header.

============================================================================

Warning: This is a beta API. It may change in future releases.

Overview

The True Random Number Generator (TRNG) module generates numbers of variable lengths from a source of entropy. The output is suitable for applications requiring cryptographically random numbers 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.
Initialize a blank CryptoKey. These opaque datastructures are representations of keying material and its storage. Depending on how the keying material is stored (RAM or flash, key store, key blob), the CryptoKey must be initialized differently. The TRNG API can handle all types of CryptoKey. However, not all device-specific implementions 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.

TRNG operations

TRNG_generateEntropy() provides the most basic functionality. Use it to generate random numbers of a specified width without further restrictions. An example use-case would be generating a symmetric key for AES encryption and / or authentication.

TRNG_generateEntropyLessThan() returns a random number with the restriction that the random number be less than a specified value. The algorithm used to ensure negligible biasing of the resultant random number is implementation dependent.

TRNG_generateEntropyNonZeroLessThan() also returns a random number with the restriction that the number be less than a specified value. Further, the number will not be zero either. This call specifically is useful if you are trying to generate a private key for use with elliptic curve cryptography. Private keys commonly have the restriction that they be within [1, n - 1], where n is the order of the curve. This function guarantees that you will have an unbiased number in that range when it returns. The algorithm used to ensure negligible biasing of the resultant random number is implementation dependent.

While TRNG_generateEntropyNonZeroLessThan() is guaranteed to produce entropy fit for use in ECC operations, it may not be the most sensible choice. TRNG_generateEntropyNonZeroLessThan() requires overhead both in code size and in run-time and thus power consumption. The order of a curve is often a large number very close to the upper bound of numbers that fit the curve parameter width. This means that, for many curves, it is improbable that a randomly generated number is an invalid private key. The ECDH public key generation functions will reject invalid private keys with an error code. This lets you implement rejection sampling by using the basic TRNG_generateEntropy() to generate a random number and simply generating a new one if the ECDH public key generation function rejects it.

Not all implementations support the more specialized functions as they require efficient operations on large numbers. Usually, this means the device needs a large number maths accelerator or public key accelerator.

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

TRNG Driver Configuration

In order to use the TRNG APIs, the application is required to provide device-specific TRNG configuration in the Board.c file. The TRNG driver interface defines a configuration data structure:

typedef struct TRNG_Config_ {
    void                   *object;
    void          const    *hwAttrs;
} TRNG_Config;

The application must declare an array of TRNG_Config elements, named TRNG_config[]. Each element of TRNG_config[] must be populated with pointers to a device specific TRNG driver implementation's driver object and hardware attributes. The hardware attributes define properties such as the TRNG peripheral's base address. Each element in TRNG_config[] corresponds to a TRNG instance and none of the elements should have NULL pointers. There is no correlation between the index and the peripheral designation (such as TRNG0 or TRNG1). For example, it is possible to use TRNG_config[0] for TRNG1. Multiple drivers and driver instances may all access the same underlying hardware. This is transparent to the application. Mutual exclusion is performed automatically by the drivers as necessary.

Because the TRNG configuration is very device dependent, you will need to check the doxygen for the device specific TRNG implementation. There you will find a description of the TRNG hardware attributes. Please also refer to the Board.c file of any of your examples to see the TRNG configuration.

TRNG Parameters

The TRNG_Params structure is passed to the TRNG_open() call. If NULL is passed for the parameters, TRNG_open() uses default parameters. A TRNG_Params structure is initialized with default values by passing it to TRNG_Params_init(). Some of the TRNG parameters are described below. To see brief descriptions of all the parameters, see TRNG_Params.

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];
handle = TRNG_open(0, NULL);
if (!handle) {
    // Handle error
    while(1);
}
CryptoKeyPlaintext_initBlankKey(&entropyKey, entropyBuffer, KEY_LENGTH_BYTES);
result = TRNG_generateEntropy(handle, &entropyKey);
if (result != TRNG_STATUS_SUCCESS) {
    // Handle error
    while(1);
}
TRNG_close(handle);

### Generate ECC private key #

#include <ti/drivers/TRNG.h>
#include <ti/drivers/cryptoutils/cryptokey/CryptoKeyPlaintext.h>
#include <ti/drivers/cryptoutils/ecc/ECCParams.h>
// The NIST-P256 curve has 256-bit curve parameters and thus 32-byte private
// keys.
#define PRIVATE_KEY_LENGTH_BYTES 32
TRNG_Handle handle;
int_fast16_t result;
CryptoKey entropyKey;
uint8_t entropyBuffer[PRIVATE_KEY_LENGTH_BYTES];
handle = TRNG_open(0, NULL);
if (!handle) {
    // Handle error
    while(1);
}
CryptoKeyPlaintext_initBlankKey(&entropyKey, entropyBuffer, ECCParams_NISTP256.length);
result = TRNG_generateEntropyNonZeroLessThan(handle,
                                             &entropyKey,
                                             ECCParams_NISTP256.order);
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_generateEntropy(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);

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

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_CMD_RESERVED (32)

#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_UNDEFINEDCMD (-2)
	An error status code returned by TRNG_control() for undefined command codes. More...

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

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

typedef enum TRNG_ReturnBehavior_	TRNG_ReturnBehavior
	The way in which TRNG function calls return after generating the requested entropy. More...

typedef struct TRNG_Config_	TRNG_Config
	TRNG Global configuration. More...

typedef void(*	TRNG_CallbackFxn) (TRNG_Handle handle, int_fast16_t returnValue, CryptoKey *entropy)
	The definition of a callback function used by the TRNG driver when used in TRNG_RETURN_BEHAVIOR_CALLBACK. More...

typedef struct TRNG_Params_	TRNG_Params
	TRNG Parameters. 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_control (TRNG_Handle handle, uint32_t cmd, void *args)
	Function performs implementation specific features on a given TRNG_Handle. More...

int_fast16_t	TRNG_generateEntropyLessThan (TRNG_Handle handle, CryptoKey entropy, const uint8_t upperBound)
	Generate a random number smaller than a number. More...

int_fast16_t	TRNG_generateEntropyNonZeroLessThan (TRNG_Handle handle, CryptoKey entropy, const uint8_t upperBound)
	Generate a random number smaller than a number but greater than 0. More...

int_fast16_t	TRNG_generateEntropy (TRNG_Handle handle, CryptoKey *entropy)
	Generate a random number. More...

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

Typedef Documentation

§ TRNG_Handle

typedef struct TRNG_Config_* TRNG_Handle

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

§ TRNG_ReturnBehavior

typedef enum TRNG_ReturnBehavior_ TRNG_ReturnBehavior

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

Not all TRNG operations exhibit the specified return behavor. Functions that do not require significant computation and cannot offload that computation to a background thread behave like regular functions. Which functions exhibit the specfied 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

§ TRNG_Config

typedef struct TRNG_Config_ TRNG_Config

TRNG Global configuration.

The TRNG_Config structure contains a set of pointers used to characterize the TRNG driver implementation.

This structure needs to be defined before calling TRNG_init() and it must not be changed thereafter.

See also: TRNG_init()

§ TRNG_CallbackFxn

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

The definition of a callback function used by the TRNG driver when used in 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.
entropy	The CryptoKey that describes the location the generated entropy will be copied to.

§ TRNG_Params

typedef struct TRNG_Params_ TRNG_Params

TRNG Parameters.

TRNG Parameters are used to with the TRNG_open() call. Default values for these parameters are set using TRNG_Params_init().

See also: TRNG_Params_init()

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 behavor. Functions that do not require significant computation and cannot offload that computation to a background thread behave like regular functions. Which functions exhibit the specfied 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

Defaults values are: returnBehavior = TRNG_RETURN_BEHAVIOR_BLOCKING callbackFxn = 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_control()

int_fast16_t TRNG_control	(	TRNG_Handle	handle,
		uint32_t	cmd,
		void *	args
	)

Function performs implementation specific features on a given TRNG_Handle.

Commands for TRNG_control can originate from TRNG.h or from implementation specific TRNG*.h (TRNGCC26XX.h, TRNGMSP432.h, etc.. ) files. While commands from TRNG.h are API portable across driver implementations, not all implementations may support all these commands. Conversely, commands from driver implementation specific TRNG*.h files add unique driver capabilities but are not API portable across all TRNG driver implementations.

Commands supported by TRNG.h follow a TRNG_CMD_<cmd> naming convention.
Commands supported by TRNG*.h follow a TRNG*_CMD_<cmd> naming convention.
Each control command defines arg differently. The types of arg are documented with each command.

See TRNG_control command codes for command codes.

See TRNG_control return status codes for status codes.

Precondition: TRNG_open() has to be called first.

Parameters

handle	A TRNG handle returned from TRNG_open()
cmd	TRNG.h or TRNG*.h commands.
args	An optional R/W (read/write) command argument accompanied with cmd

Returns: Implementation specific return codes. Negative values indicate unsuccessful operations.

See also: TRNG_open()

§ TRNG_generateEntropyLessThan()

int_fast16_t TRNG_generateEntropyLessThan	(	TRNG_Handle	handle,
		CryptoKey *	entropy,
		const uint8_t *	upperBound
	)

Generate a random number smaller than a number.

Generates a random bitstream of the size defined in the entropy CryptoKey in the range 0 <= entropy buffer < upperBound. The entropy will be generated and stored according to the storage requirements defined in the CryptoKey.

upperBound must have the same length as defined in entropy.

Precondition: TRNG_open() has to be called first.

Parameters

handle	A TRNG handle returned from TRNG_open().
entropy	A blank, initialized CryptoKey describing the target location the entropy shall be stored in.
upperBound	The uppper bound of numbers returned, exclusive.

§ TRNG_generateEntropyNonZeroLessThan()

int_fast16_t TRNG_generateEntropyNonZeroLessThan	(	TRNG_Handle	handle,
		CryptoKey *	entropy,
		const uint8_t *	upperBound
	)

Generate a random number smaller than a number but greater than 0.

Generates a random bitstream of the size defined in the entropy CryptoKey in the range 0 < entropy buffer < upperBound. The entropy will be generated and stored according to the storage requirements defined in the CryptoKey.

upperBound must have the same length as defined in entropy.

Precondition: TRNG_open() has to be called first.

Parameters

handle	A TRNG handle returned from TRNG_open().
entropy	A blank, initialized CryptoKey describing the target location the entropy shall be stored in.
upperBound	The uppper bound of numbers returned, exclusive.

§ TRNG_generateEntropy()

int_fast16_t TRNG_generateEntropy	(	TRNG_Handle	handle,
		CryptoKey *	entropy
	)

Generate a random number.

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.

Precondition: TRNG_open() has to be called first.

Parameters

handle	A TRNG handle returned from TRNG_open().
entropy	A blank, initialized CryptoKey describing the target location the entropy shall be stored in.

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

TRNG Driver Configuration

TRNG Parameters

Examples

Generate ECC private and public key using rejection sampling

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Typedef Documentation

§ TRNG_Handle

§ TRNG_ReturnBehavior

§ TRNG_Config

§ TRNG_CallbackFxn

§ TRNG_Params

Enumeration Type Documentation

§ TRNG_ReturnBehavior_

Function Documentation

§ TRNG_init()

§ TRNG_Params_init()

§ TRNG_open()

§ TRNG_close()

§ TRNG_control()

§ TRNG_generateEntropyLessThan()

§ TRNG_generateEntropyNonZeroLessThan()

§ TRNG_generateEntropy()

Variable Documentation

§ TRNG_defaultParams