MCUXpresso SDK API Reference Manual  Rev. 0
NXP Semiconductors
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
TRNG: True Random Number Generator

Overview

The MCUXpresso SDK provides a peripheral driver for the True Random Number Generator (TRNG) module of MCUXpresso SDK devices.

The True Random Number Generator is a hardware accelerator module that generates a 512-bit entropy as needed by an entropy consuming module or by other post processing functions. A typical entropy consumer is a pseudo random number generator (PRNG) which can be implemented to achieve both true randomness and cryptographic strength random numbers using the TRNG output as its entropy seed. The entropy generated by a TRNG is intended for direct use by functions that generate secret keys, per-message secrets, random challenges, and other similar quantities used in cryptographic algorithms.

TRNG Initialization

  1. Define the TRNG user configuration structure. Use TRNG_InitUserConfigDefault() function to set it to default TRNG configuration values.
  2. Initialize the TRNG module, call the TRNG_Init() function, and pass the user configuration structure. This function automatically enables the TRNG module and its clock. After that, the TRNG is enabled and the entropy generation starts working.
  3. To disable the TRNG module, call the TRNG_Deinit() function.

Get random data from TRNG

  1. TRNG_GetRandomData() function gets random data from the TRNG module.

This example code shows how to initialize and get random data from the TRNG driver.

Refer to the driver examples codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/trng

Data Structures

struct  trng_statistical_check_limit_t
 Data structure for definition of statistical check limits. More...
 
struct  trng_config_t
 Data structure for the TRNG initialization. More...
 

Enumerations

enum  trng_sample_mode_t {
  kTRNG_SampleModeVonNeumann = 0U,
  kTRNG_SampleModeRaw = 1U,
  kTRNG_SampleModeVonNeumannRaw
}
 TRNG sample mode. More...
 
enum  trng_clock_mode_t {
  kTRNG_ClockModeRingOscillator = 0U,
  kTRNG_ClockModeSystem = 1U
}
 TRNG clock mode. More...
 
enum  trng_ring_osc_div_t {
  kTRNG_RingOscDiv0 = 0U,
  kTRNG_RingOscDiv2 = 1U,
  kTRNG_RingOscDiv4 = 2U,
  kTRNG_RingOscDiv8 = 3U
}
 TRNG ring oscillator divide. More...
 

Functions

status_t TRNG_GetDefaultConfig (trng_config_t *userConfig)
 Initializes the user configuration structure to default values. More...
 
status_t TRNG_Init (TRNG_Type *base, const trng_config_t *userConfig)
 Initializes the TRNG. More...
 
void TRNG_Deinit (TRNG_Type *base)
 Shuts down the TRNG. More...
 
status_t TRNG_GetRandomData (TRNG_Type *base, void *data, size_t dataSize)
 Gets random data. More...
 

Driver version

#define FSL_TRNG_DRIVER_VERSION   (MAKE_VERSION(2, 0, 8))
 TRNG driver version 2.0.8. More...
 

Data Structure Documentation

struct trng_statistical_check_limit_t

Used by trng_config_t.

Data Fields

uint32_t maximum
 Maximum limit. More...
 
uint32_t minimum
 Minimum limit. More...
 

Field Documentation

uint32_t trng_statistical_check_limit_t::maximum
uint32_t trng_statistical_check_limit_t::minimum
struct trng_config_t

This structure initializes the TRNG by calling the TRNG_Init() function. It contains all TRNG configurations.

Data Fields

bool lock
 Disable programmability of TRNG registers. More...
 
trng_clock_mode_t clockMode
 Clock mode used to operate TRNG. More...
 
trng_ring_osc_div_t ringOscDiv
 Ring oscillator divide used by TRNG. More...
 
trng_sample_mode_t sampleMode
 Sample mode of the TRNG ring oscillator. More...
 
uint16_t entropyDelay
 Entropy Delay. More...
 
uint16_t sampleSize
 Sample Size. More...
 
uint16_t sparseBitLimit
 Sparse Bit Limit which defines the maximum number of consecutive samples that may be discarded before an error is generated. More...
 
uint8_t retryCount
 Retry count. More...
 
uint8_t longRunMaxLimit
 Largest allowable number of consecutive samples of all 1, or all 0, that is allowed during the Entropy generation. More...
 
trng_statistical_check_limit_t monobitLimit
 Maximum and minimum limits for statistical check of number of ones/zero detected during entropy generation. More...
 
trng_statistical_check_limit_t runBit1Limit
 Maximum and minimum limits for statistical check of number of runs of length 1 detected during entropy generation. More...
 
trng_statistical_check_limit_t runBit2Limit
 Maximum and minimum limits for statistical check of number of runs of length 2 detected during entropy generation. More...
 
trng_statistical_check_limit_t runBit3Limit
 Maximum and minimum limits for statistical check of number of runs of length 3 detected during entropy generation. More...
 
trng_statistical_check_limit_t runBit4Limit
 Maximum and minimum limits for statistical check of number of runs of length 4 detected during entropy generation. More...
 
trng_statistical_check_limit_t runBit5Limit
 Maximum and minimum limits for statistical check of number of runs of length 5 detected during entropy generation. More...
 
trng_statistical_check_limit_t runBit6PlusLimit
 Maximum and minimum limits for statistical check of number of runs of length 6 or more detected during entropy generation. More...
 
trng_statistical_check_limit_t pokerLimit
 Maximum and minimum limits for statistical check of "Poker Test". More...
 
trng_statistical_check_limit_t frequencyCountLimit
 Maximum and minimum limits for statistical check of entropy sample frequency count. More...
 

Field Documentation

bool trng_config_t::lock
trng_clock_mode_t trng_config_t::clockMode
trng_ring_osc_div_t trng_config_t::ringOscDiv
trng_sample_mode_t trng_config_t::sampleMode
uint16_t trng_config_t::entropyDelay

Defines the length (in system clocks) of each Entropy sample taken.

uint16_t trng_config_t::sampleSize

Defines the total number of Entropy samples that will be taken during Entropy generation.

uint16_t trng_config_t::sparseBitLimit

This limit is used only for during von Neumann sampling (enabled by TRNG_HAL_SetSampleMode()). Samples are discarded if two consecutive raw samples are both 0 or both 1. If this discarding occurs for a long period of time, it indicates that there is insufficient Entropy.

uint8_t trng_config_t::retryCount

It defines the number of times a statistical check may fails during the TRNG Entropy Generation before generating an error.

uint8_t trng_config_t::longRunMaxLimit
trng_statistical_check_limit_t trng_config_t::monobitLimit
trng_statistical_check_limit_t trng_config_t::runBit1Limit
trng_statistical_check_limit_t trng_config_t::runBit2Limit
trng_statistical_check_limit_t trng_config_t::runBit3Limit
trng_statistical_check_limit_t trng_config_t::runBit4Limit
trng_statistical_check_limit_t trng_config_t::runBit5Limit
trng_statistical_check_limit_t trng_config_t::runBit6PlusLimit
trng_statistical_check_limit_t trng_config_t::pokerLimit
trng_statistical_check_limit_t trng_config_t::frequencyCountLimit

Macro Definition Documentation

#define FSL_TRNG_DRIVER_VERSION   (MAKE_VERSION(2, 0, 8))

Current version: 2.0.8

Change log:

  • version 2.0.8
    • For K32L2A41A_SERIES set TRNG_USER_CONFIG_DEFAULT_OSC_DIV to kTRNG_RingOscDiv4.
  • version 2.0.7
    • Fix MISRA 2004 issue rule 12.5.
  • version 2.0.6
    • For KW35Z4_SERIES set TRNG_USER_CONFIG_DEFAULT_OSC_DIV to kTRNG_RingOscDiv8.
  • version 2.0.5
    • Add possibility to define default TRNG configuration by device specific preprocessor macros for FRQMIN, FRQMAX and OSCDIV.
  • version 2.0.4
    • Fix MISRA-2012 issues.
  • Version 2.0.3
    • update TRNG_Init to restart entropy generation
  • Version 2.0.2
    • fix MISRA issues
  • Version 2.0.1
    • add support for KL8x and KL28Z
    • update default OSCDIV for K81 to divide by 2

Enumeration Type Documentation

Used by trng_config_t.

Enumerator
kTRNG_SampleModeVonNeumann 

Use von Neumann data in both Entropy shifter and Statistical Checker.

kTRNG_SampleModeRaw 

Use raw data into both Entropy shifter and Statistical Checker.

kTRNG_SampleModeVonNeumannRaw 

Use von Neumann data in Entropy shifter.

Use raw data into Statistical Checker.

Used by trng_config_t.

Enumerator
kTRNG_ClockModeRingOscillator 

Ring oscillator is used to operate the TRNG (default).

kTRNG_ClockModeSystem 

System clock is used to operate the TRNG.

This is for test use only, and indeterminate results may occur.

Used by trng_config_t.

Enumerator
kTRNG_RingOscDiv0 

Ring oscillator with no divide.

kTRNG_RingOscDiv2 

Ring oscillator divided-by-2.

kTRNG_RingOscDiv4 

Ring oscillator divided-by-4.

kTRNG_RingOscDiv8 

Ring oscillator divided-by-8.

Function Documentation

status_t TRNG_GetDefaultConfig ( trng_config_t userConfig)

This function initializes the configuration structure to default values. The default values are as follows.

* user_config->lock = 0;
* user_config->clockMode = kTRNG_ClockModeRingOscillator;
* user_config->ringOscDiv = kTRNG_RingOscDiv0; Or to other kTRNG_RingOscDiv[2|8] depending on the platform.
* user_config->sampleMode = kTRNG_SampleModeRaw;
* user_config->entropyDelay = 3200;
* user_config->sampleSize = 2500;
* user_config->sparseBitLimit = TRNG_USER_CONFIG_DEFAULT_SPARSE_BIT_LIMIT;
* user_config->retryCount = 63;
* user_config->longRunMaxLimit = 34;
* user_config->monobitLimit.maximum = 1384;
* user_config->monobitLimit.minimum = 1116;
* user_config->runBit1Limit.maximum = 405;
* user_config->runBit1Limit.minimum = 227;
* user_config->runBit2Limit.maximum = 220;
* user_config->runBit2Limit.minimum = 98;
* user_config->runBit3Limit.maximum = 125;
* user_config->runBit3Limit.minimum = 37;
* user_config->runBit4Limit.maximum = 75;
* user_config->runBit4Limit.minimum = 11;
* user_config->runBit5Limit.maximum = 47;
* user_config->runBit5Limit.minimum = 1;
* user_config->runBit6PlusLimit.maximum = 47;
* user_config->runBit6PlusLimit.minimum = 1;
* user_config->pokerLimit.maximum = 26912;
* user_config->pokerLimit.minimum = 24445;
* user_config->frequencyCountLimit.maximum = 25600;
* user_config->frequencyCountLimit.minimum = 1600;
*
Parameters
user_configUser configuration structure.
Returns
If successful, returns the kStatus_TRNG_Success. Otherwise, it returns an error.
status_t TRNG_Init ( TRNG_Type *  base,
const trng_config_t userConfig 
)

This function initializes the TRNG. When called, the TRNG entropy generation starts immediately.

Parameters
baseTRNG base address
userConfigPointer to the initialization configuration structure.
Returns
If successful, returns the kStatus_TRNG_Success. Otherwise, it returns an error.
void TRNG_Deinit ( TRNG_Type *  base)

This function shuts down the TRNG.

Parameters
baseTRNG base address.
status_t TRNG_GetRandomData ( TRNG_Type *  base,
void *  data,
size_t  dataSize 
)

This function gets random data from the TRNG.

Parameters
baseTRNG base address.
dataPointer address used to store random data.
dataSizeSize of the buffer pointed by the data parameter.
Returns
random data