Macros | Functions
Random.h File Reference

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;
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.

Returns
Returns a status code
See also
Random_seedManual()
Postcondition
Random_getNumber()
Random_getBytes()

§ Random_seedManual()

void Random_seedManual ( uint8_t  seed[(20)])

Set the internal state to a specified seed.

This function sets the internal state to the seed specified by the application.

Parameters
seedSeed to set the internal state to
See also
Random_seedAutomatic()
Postcondition
Random_getNumber()
Random_getBytes()

§ Random_getNumber()

uint32_t Random_getNumber ( void  )

Returns a random number.

This function returns a random number and updates the internal state.

Returns
Returns random number
Precondition
Random_seedAutomatic()
Random_seedManual()

§ Random_getBytes()

void Random_getBytes ( void *  buffer,
size_t  bufferSize 
)

Returns a number of random bytes

This is a convenience function that fills the specified array with random bytes by repeatedly calling Random_getNumber().

Parameters
bufferBuffer to fill with random bytes
bufferSizeSize of buffer. Any value is permitted, including those that are not multiples of sizeof(uint32_t).
Precondition
Random_seedAutomatic()
Random_seedManual()
© Copyright 1995-2020, Texas Instruments Incorporated. All rights reserved.
Trademarks | Privacy policy | Terms of use | Terms of sale