Detailed Description

TRNG driver implementation for the CC26X2 family.

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

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

This file should only be included in the board file to fill the TRNG_config struct.

The CC26X2 family has a dedicated hardware TRNG based on sampling multiple free running oscillators. With all FROs enabled, the TRNG hardware generates 64 bits of entropy approximately every 5ms. The driver implementation chains multiple 64-bit entropy generation operations together to generate an arbitrary amount of entropy.

When using TRNG_generateEntropyLessThan() and TRNG_generateEntropyNonZeroLessThan(), there is a restriction on the maximum entropy length that may be generated. The driver implements a variant from BSI Technical Guideline TR-03111 to generate a random number less than some upper bound that is also unbiased. This requires generating more entropy than explicitely requested and performing modulo operations on it. This intermediate entropy is stored in the PKA RAM before the PKA reduces it. This limits the maximum length of the generated entropy to 768 bytes. In practice, this should not prove to be a problem. The largest number you would reasonably want to generate that is less than some upper bound is a private key for the NIST P521 curve. It has a 66-byte curve parameter length and thus also private key length.

Since TRNG_generateEntropyLessThan() and TRNG_generateEntropyNonZeroLessThan() both use the PKA module, the driver must acquire the PKA semaphore as well as the TRNG semaphore. This is implemented transparently to the application and the driver will return an error if it did not acquire both semaphores for the above operations.

The driver implementation does not perform runtime checks for most input parameters. Only values that are likely to have a stochastic element to them are checked (such as whether a driver is already open). Higher input paramter validation coverage is achieved by turning on assertions when compiling the driver.

#include <stdint.h>
#include <stdbool.h>
#include <ti/drivers/Power.h>
#include <ti/drivers/TRNG.h>
#include <ti/drivers/cryptoutils/cryptokey/CryptoKey.h>
#include <ti/drivers/dpl/HwiP.h>
#include <ti/drivers/dpl/SwiP.h>
#include <ti/drivers/dpl/SemaphoreP.h>

Include dependency graph for TRNGCC26X2.h:

Go to the source code of this file.

Data Structures
struct	TRNGCC26X2_HWAttrs
	TRNGCC26X2 Hardware Attributes. More...

struct	TRNGCC26X2_Object
	TRNGCC26XX Object. More...

Macros
#define	TRNGCC26X2_SAMPLES_PER_CYCLE_MIN 256

#define	TRNGCC26X2_SAMPLES_PER_CYCLE_DEFAULT 240000

#define	TRNGCC26X2_SAMPLES_PER_CYCLE_MAX 16777216

Typedefs
typedef struct TRNGCC26X2_HWAttrs	TRNGCC26X2_HWAttrs
	TRNGCC26X2 Hardware Attributes. More...

typedef struct TRNGCC26X2_Object	TRNGCC26X2_Object
	TRNGCC26XX Object. More...

Functions
int_fast16_t	TRNGCC26X2_setSamplesPerCycle (TRNG_Handle handle, uint32_t samplesPerCycle)
	Sets the number of entropy generation cycles before the results are returned. More...

Macro Definition Documentation

§ TRNGCC26X2_SAMPLES_PER_CYCLE_MIN

#define TRNGCC26X2_SAMPLES_PER_CYCLE_MIN 256

Minimum number of times the TRNG samples the randomness source for each entropy generation cycle.

§ TRNGCC26X2_SAMPLES_PER_CYCLE_DEFAULT

#define TRNGCC26X2_SAMPLES_PER_CYCLE_DEFAULT 240000

Default number of times the TRNG samples the randomness source for each entropy generation cycle. Set to generate 64 bits of randomness in 5ms with all FROs active.

§ TRNGCC26X2_SAMPLES_PER_CYCLE_MAX

#define TRNGCC26X2_SAMPLES_PER_CYCLE_MAX 16777216

Maximum number of times the TRNG samples the randomness source for each entropy generation cycle.

Typedef Documentation

§ TRNGCC26X2_HWAttrs

typedef struct TRNGCC26X2_HWAttrs TRNGCC26X2_HWAttrs

TRNGCC26X2 Hardware Attributes.

TRNG26X2 hardware attributes should be included in the board file and pointed to by the TRNG_config struct.

§ TRNGCC26X2_Object

typedef struct TRNGCC26X2_Object TRNGCC26X2_Object

TRNGCC26XX Object.

The application must not access any member variables of this structure!

Function Documentation

§ TRNGCC26X2_setSamplesPerCycle()

int_fast16_t TRNGCC26X2_setSamplesPerCycle	(	TRNG_Handle	handle,
		uint32_t	samplesPerCycle
	)

Sets the number of entropy generation cycles before the results are returned.

The default value is set to generate 64 bits of entropy.

Precondition: TRNG_open() has to be called first successfully

Parameters

handle	A TRNGCC26X2 handle returned from TRNGCC26X2_open
samplesPerCycle	Number of 48MHz clock cycles to sample. Must be between 2^8 and 2^24.

See also: TRNG_open()