Detailed Description

Interface to generate pseudo-random numbers.

Warning: The numbers generated by this module are not crpytographically-secure! Do not use this module to generate keying material or for other security-related purposes!

This module generates non-cryptographically-secure random numbers in an easy to use and fast way.

There is a single global state that must be initialised by calling Random_seedAutomatic() or Random_seedManual(). Afterwards, you can call Random_getNumber() or Random_getBytes() as desired. Both are thread-safe and protect the internal state.

The pseudo-random number generator used is the "xorwow" algorithm specified in Marsaglia's "Xorshift RNGs" paper. It keeps 20 bytes of state that must be seeded and has a period of 2^160 - 2^32 before a sequence wraps.

Generating a random number with this algorithm is quite fast. Random_getNumber() only requires 82 instructions which is 1.7us on a 48MHz Cortex M4. That includes disabling interrupts.

int_fast16_t status;
uint32_t randomNumber;
status = Random_seedAutomatic();
if (status != Random_STATUS_SUCCESS) {
     while(1);
}
randomNumber = Random_getNumber();

#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>

Include dependency graph for Random.h:

Go to the source code of this file.

Macros
#define	Random_STATUS_SUCCESS (0)

#define	Random_STATUS_ERROR (-1)

#define	Random_SEED_LENGTH (20)
	Length of the seed in bytes. More...

Functions
int_fast16_t	Random_seedAutomatic (void)
	Seed internal state automatically. More...

void	Random_seedManual (uint8_t seed[(20)])
	Set the internal state to a specified seed. More...

uint32_t	Random_getNumber (void)
	Returns a random number. More...

void	Random_getBytes (void *buffer, size_t bufferSize)

Macro Definition Documentation

§ Random_STATUS_SUCCESS

#define Random_STATUS_SUCCESS (0)

§ Random_STATUS_ERROR

#define Random_STATUS_ERROR (-1)

§ Random_SEED_LENGTH

#define Random_SEED_LENGTH (20)

Length of the seed in bytes.

Function Documentation

§ Random_seedAutomatic()

int_fast16_t Random_seedAutomatic ( void )

Seed internal state automatically.

This function seeds or reseeds the internal state. The method for generating the seed is device dependent.

If a TRNG is available, it will be used to generate the seed.

If a TRNG is not available, information unique to the device running the code will be used. This may be a unique device identifier or other information such as a MAC address. Since the seed is constant per device for devices without a TRNG, the number sequence will restart after each call to Random_seedAutomatic(). This will usually occur after rebooting the device.

If neither a TRNG nor a unique device identifier is available, a constant will be used.