TRNG driver header.
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.
Before starting a TRNG operation, the application must do the following:
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, the application should either start another operation or close the driver by calling TRNG_close().
#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_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... | |
#define | TRNG_STATUS_KEYSTORE_ERROR (-5) |
Importing generated key into KeyStore failed. 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... | |
#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 TRNG_STATUS_SUCCESS (0) |
Successful status code.
Functions return TRNG_STATUS_SUCCESS if the function was executed successfully.
#define TRNG_STATUS_ERROR (-1) |
Generic error status code.
Functions return TRNG_STATUS_ERROR if the function was not executed successfully.
#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.
#define TRNG_STATUS_INVALID_INPUTS (-3) |
Operation failed due to invalid inputs.
Functions return TRNG_STATUS_INVALID_INPUTS if input validation fails.
#define TRNG_STATUS_CANCELED (-4) |
The ongoing operation was canceled.
#define TRNG_STATUS_KEYSTORE_ERROR (-5) |
Importing generated key into KeyStore failed.
Functions return TRNG_STATUS_KEYSTORE_ERROR if the KeyStore_PSA_importKey() did not return KEYSTORE_PSA_STATUS_SUCCESS
typedef TRNG_Config* TRNG_Handle |
A handle that is returned from a TRNG_open() call.
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.
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. |
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.
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. |
The definition of a callback function used by the TRNG driver when used in TRNG_RETURN_BEHAVIOR_CALLBACK.
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 |
void TRNG_init | ( | void | ) |
This function initializes the TRNG module.
void TRNG_Params_init | ( | TRNG_Params * | params | ) |
Function to initialize the TRNG_Params struct to its defaults.
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_Handle TRNG_open | ( | uint_least8_t | index, |
TRNG_Params * | params | ||
) |
This function opens a given TRNG peripheral.
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. |
void TRNG_close | ( | TRNG_Handle | handle | ) |
Function to close a TRNG peripheral specified by the TRNG handle.
handle | A TRNG handle returned from TRNG_open() |
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.
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. |
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. |
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.
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. |
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. |
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
.
CryptoKey
instead.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. |
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_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.
config | TRNG_Config describing the location of the object and hwAttrs. |
params | TRNG_Params to configure the driver instance. |
config
points to must be zeroed out prior to calling this function. Otherwise, unexpected behavior may ensue. 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.
handle | A TRNG_Handle returned from TRNG_open() |
TRNG_STATUS_SUCCESS | The operation was canceled or there was no operation in progress to be canceled. |
const TRNG_Params TRNG_defaultParams |
Default TRNG_Params structure.