| Kinetis SDK v.2.0 API Reference Manual Rev. 0 Freescale Semiconductor, Inc.

- Main Page
- Related Pages
- API Reference

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Files | Enumerations | Functions
RNGA: Random Number Generator Accelerator Driver

## Overview

The Kinetis SDK provides Peripheral driver for the Random Number Generator Accelerator (RNGA) block of Kinetis devices.

# RNGA Initialization

1. To initialize the RNGA module, call the RNGA_Init() function. This function automatically enables the RNGA module and its clock.
2. After calling the RNGA_Init() function, the RNGA is enabled and the counter starts working.
3. To disable the RNGA module, call the RNGA_Deinit() function.

# Get random data from RNGA

1. RNGA_GetRandomData() function gets random data from the RNGA module.

# RNGA Set/Get Working Mode

The RNGA works either in sleep mode or normal mode

1. RNGA_SetMode() function sets the RNGA mode.
2. RNGA_GetMode() function gets the RNGA working mode.

# Seed RNGA

1. RNGA_Seed() function inputs an entropy value that the RNGA can use to seed the pseudo random algorithm.

This example code shows how to initialize and get random data from the RNGA driver:

{
status_t status;
uint32_t data;
/* Initialize RNGA
status = RNGA_Init(RNG);
/* Read Random data
status = RNGA_GetRandomData(RNG, data, sizeof(data));
if(status == kStatus_Success)
{
/* Print data
PRINTF("Random = 0x%X\r\n", i, data );
PRINTF("Succeed.\r\n");
}
else
{
PRINTF("RNGA failed! (0x%x)\r\n", status);
}
/* Deinitialize RNGA
RNGA_Deinit(RNG);
}

Note
  It is important to note there is no known cryptographic proof showing this is a secure method of generating random data. In fact, there may be an attack against this random number generator if its output is used directly in a cryptographic application. The attack is based on the linearity of the internal shift registers. Therefore, it is highly recommended that this random data produced by this module be used as an entropy source to provide an input seed to a NIST-approved pseudo-random-number generator based on DES or SHA-1 and defined in NIST FIPS PUB 186-2 Appendix 3 and NIST FIPS PUB SP 800-90. The requirement is to maximize the entropy of this input seed. In order to do this, when data is extracted from RNGA as quickly as the hardware allows, there are about one or two bits of added entropy per 32-bit word. Any single bit of that word contains that entropy. Therefore, when used as an entropy source, a random number should be generated for each bit of entropy required, and the least significant bit (any bit would be equivalent) of each word retained. The remainder of each random number should then be discarded. Used this way, even with full knowledge of the internal state of RNGA and all prior random numbers, an attacker is not able to predict the values of the extracted bits. Other sources of entropy can be used along with RNGA to generate the seed to the pseudorandom algorithm. The more random sources combined to create the seed, the better. The following is a list of sources that can be easily combined with the output of this module:
  - Current time using highest precision possible
  - Real-time system inputs that can be characterized as "random"
  - Other entropy supplied directly by the user

## Files
file | fsl_rnga.h

## Enumerations
enum | rnga_mode_t { kRNGA_ModeNormal = 0U, kRNGA_ModeSleep = 1U }
| RNGA working mode. More...

## Functions
void | RNGA_Init (RNG_Type *base)
| Initializes the RNGA. More...
void | RNGA_Deinit (RNG_Type *base)
| Shuts down the RNGA. More...
status_t | RNGA_GetRandomData (RNG_Type *base, void *data, size_t data_size)
| Gets random data. More...
void | RNGA_Seed (RNG_Type *base, uint32_t seed)
| Feeds the RNGA module. More...
void | RNGA_SetMode (RNG_Type *base, rnga_mode_t mode)
| Sets the RNGA in normal mode or sleep mode. More...
rnga_mode_t | RNGA_GetMode (RNG_Type *base)
| Gets the RNGA working mode. More...

## Driver version
#define | FSL_RNGA_DRIVER_VERSION (MAKE_VERSION(2, 0, 1))
| RNGA driver version 2.0.1. More...

## Macro Definition Documentation

#define FSL_RNGA_DRIVER_VERSION (MAKE_VERSION(2, 0, 1))

## Enumeration Type Documentation

enum rnga_mode_t

Enumerator
kRNGA_ModeNormal | Normal Mode. The ring-oscillator clocks are active; RNGA generates entropy (randomness) from the clocks and stores it in shift registers.
kRNGA_ModeSleep | Sleep Mode. The ring-oscillator clocks are inactive; RNGA does not generate entropy.

## Function Documentation

void RNGA_Init | ( | RNG_Type * | base | ) |

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

Parameters

  base | RNGA base address

void RNGA_Deinit | ( | RNG_Type * | base | ) |

This function shuts down the RNGA.

Parameters

  base | RNGA base address

status_t RNGA_GetRandomData | ( | RNG_Type * | base,
|  | void * | data,
|  | size_t | data_size
| ) |  |

This function gets random data from the RNGA.

Parameters

  base | RNGA base address
  data | pointer to user buffer to be filled by random data
  data_size | size of data in bytes

Returns
  RNGA status

void RNGA_Seed | ( | RNG_Type * | base,
|  | uint32_t | seed
| ) |  |

This function inputs an entropy value that the RNGA uses to seed its pseudo-random algorithm.

Parameters

  base | RNGA base address
  seed | input seed value

void RNGA_SetMode | ( | RNG_Type * | base,
|  | rnga_mode_t | mode
| ) |  |

This function sets the RNGA in sleep mode or normal mode.

Parameters

  base | RNGA base address
  mode | normal mode or sleep mode

rnga_mode_t RNGA_GetMode | ( | RNG_Type * | base | ) |

This function gets the RNGA working mode.

Parameters

  base | RNGA base address

Returns
  normal mode or sleep mode