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-901: 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 standard1. 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:

  • Reseed interval - the number of calls to CTR_DRBG after which it is reseeded. (default: every 10000 calls)
  • Personalisation string - An optional string that will be added to the seed on initialisation to differentiate this instantiation from others. This should uniquely identify the current instantiation (see section 8.7.1 of the NIST paper1).
  • Prediction resistance - If this is enabled, reseeding occurs every call, not just on the specified interval. (default: disabled)
  • Entropy length - The amount of entropy to use on each (re)seed (default: 32 bytes).

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:

  • If the entropy source fails for some reason
  • If the requested amount of random is too large
  • If the input data buffer used to seed the algorithm is too large

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