Random Number Generator (RNG) Module Level Design
This document describes the internal functionality of the mbed TLS Random Number Generator (RNG) module.
The Random number generator (RNG) module provides a function for random number generation.
It uses an algorithm from NIST SP 800-90A Rev. 11: 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.
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:
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:
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.
The following scenario initialises state and retrieves a random number.
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 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.
The following scenario initialises state, gathers entropy, and reseeds the RNG.
1. E. Barker, J. Kelsey, "Recommendation for Random Number Generation Using Deterministic Random Bit Generators", NIST Special Publication, 800-90A Rev. 1, June 2015, link