# Random Number Generator (RNG) Module Level Design

## Introduction

This document describes the internal functionality of the mbed TLS Random Number Generator (RNG) module.

## Component overview

The Random number generator (RNG) module provides a function for random number generation.

It uses an algorithm from NIST SP 800-90^{1}: CTR_DRBG (Counter-mode block-cipher-based Deterministic Random Bit Generator). The underlying algorithm used is AES-256 in counter mode. Entropy is gathered using a given entropy callback function, which will also be discussed in this MLD.

This module can be used to generate random numbers. The CTR_DRBG sub-module interacts with the AES-256 sub-module and the entropy collector sub-module interacts with the SHA-512 sub-module.

## CTR_DRBG

The random number generator is implemented as described in the NIST standard^{1}. Entropy is gathered using a callback function which is given at initialization. This callback is called both on initialisation and when reseeding is required.

Aside from the entropy function, the following settings are available:

Once the module has been initialised, random numbers can be requested from it. During such a request, optional additional data can be passed, which will be included when updating the CTR_DRBG algorithm's internal state.

This module can return errors in the following situations:

### Used structures

A structure is defined to represent internal state. It contains the elements from the CTR_DRBG algorithm. This internal state structure contains the counter and AES context used by the CTR_DRBG algorithm, and the settings specified on initialisation.

### Scenarios

The following scenario initialises state and retrieves a random number.

## Entropy

The entropy module allows CTR_DRBG to reseed using gathered entropy.

Entropy is gathered on two occasions: during a call from CTR_DRBG, and manually when an application calls the entropy gather function. mbed TLS uses a number of different sources for its entropy, which will be discussed in the next section. Gathered entropy is accumulated using a SHA-512 update function. Once a reseed is triggered, the SHA-512 function is finalised. The results of this first SHA-512 function are then hashed again, and returned.

### Entropy Sources

Entropy Sources are non-blocking. A counter is maintained for every source, which counts the number of bits that were returned on each gather call. A minimum number of entropy bits can be set per source. This value is checked during calls to the reseed function. If not enough entropy was gathered from a given source, the reseed function blocks until enough entropy has been gathered from that source. On completion of the reseed function, it will reset the source counters.

On Linux, **/dev/urandom** is used by default. On Windows, the **CryptGenRandom()** function is used. Further, on both platforms, the platform high resolution timer is used (rdtsc) as a source. Optionally, an implementation of the HAVEGE rng can be used to gather further entropy. Another option is to provide platform specific sources to the entropy module.

### Scenarios

The following scenario initialises state, gathers entropy, and reseeds the RNG.

## References

^{1. E. Barker, J. Kelsey, "Recommendation for Random Number Generation Using Deterministic Random Bit Generators", NIST Special Publication, 800-90, March 2007, link}