#include <random.h>
#include <compat/cpuid.h>
#include <crypto/sha256.h>
#include <crypto/sha512.h>
#include <support/cleanse.h>
#include <logging.h>
#include <randomenv.h>
#include <support/allocators/secure.h>
#include <sync.h>
#include <util/time.h>
#include <stdlib.h>
#include <thread>
#include <fcntl.h>
#include <sys/time.h>

Include dependency graph for random.cpp:

Enumerations
enum class	RNGLevel { FAST , SLOW , PERIODIC }

Functions
static void	RandFailure ()

static int64_t	GetPerformanceCounter () noexcept

static void	InitHardwareRand ()

static void	ReportHardwareRand ()

static void	SeedHardwareFast (CSHA512 &hasher) noexcept
	Add 64 bits of entropy gathered from hardware to hasher. More...

static void	SeedHardwareSlow (CSHA512 &hasher) noexcept
	Add 256 bits of entropy gathered from hardware to hasher. More...

static void	Strengthen (const unsigned char(&seed)[32], int microseconds, CSHA512 &hasher) noexcept
	Use repeated SHA512 to strengthen the randomness in seed32, and feed into hasher. More...

static void	GetDevURandom (unsigned char *ent32)
	Fallback: get 32 bytes of system entropy from /dev/urandom. More...

void	GetOSRand (unsigned char *ent32)
	Get 32 bytes of system entropy. More...

static void	SeedTimestamp (CSHA512 &hasher) noexcept

static void	SeedFast (CSHA512 &hasher) noexcept

static void	SeedSlow (CSHA512 &hasher, RNGState &rng) noexcept

static void	SeedStrengthen (CSHA512 &hasher, RNGState &rng, int microseconds) noexcept
	Extract entropy from rng, strengthen it, and feed it into hasher. More...

static void	SeedPeriodic (CSHA512 &hasher, RNGState &rng) noexcept

static void	SeedStartup (CSHA512 &hasher, RNGState &rng) noexcept

static void	ProcRand (unsigned char *out, int num, RNGLevel level) noexcept

void	GetRandBytes (unsigned char *buf, int num) noexcept
	Overall design of the RNG and entropy sources. More...

void	GetStrongRandBytes (unsigned char *buf, int num) noexcept
	Gather entropy from various sources, feed it into the internal PRNG, and generate random data using it. More...

void	RandAddPeriodic () noexcept
	Gather entropy from various expensive sources, and feed them to the PRNG state. More...

void	RandAddEvent (const uint32_t event_info) noexcept
	Gathers entropy from the low bits of the time at which events occur. More...

uint64_t	GetRand (uint64_t nMax) noexcept
	Generate a uniform random integer in the range [0..range). More...

int	GetRandInt (int nMax) noexcept

uint256	GetRandHash () noexcept

bool	Random_SanityCheck ()
	Check that OS randomness is available and returning the requested number of bytes. More...

void	RandomInit ()
	Initialize global RNG state and log any CPU features that are used. More...

Variables
bool	g_mock_deterministic_tests {false}
	Flag to make GetRand in random.h return the same number. More...

Enumeration Type Documentation

◆ RNGLevel

enum class RNGLevel

strong

Enumerator
FAST	Automatically called by GetRandBytes.
SLOW	Automatically called by GetStrongRandBytes.
PERIODIC	Called by RandAddPeriodic()

Definition at line 549 of file random.cpp.

Function Documentation

◆ GetDevURandom()

static void GetDevURandom ( unsigned char * ent32 )

static

Fallback: get 32 bytes of system entropy from /dev/urandom.

The most compatible way to get cryptographic randomness on UNIX-ish platforms.

Definition at line 256 of file random.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ GetOSRand()

void GetOSRand ( unsigned char * ent32 )

Get 32 bytes of system entropy.

Do not use this in application code: use GetStrongRandBytes instead.

Definition at line 276 of file random.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ GetPerformanceCounter()

static int64_t GetPerformanceCounter ( )

inlinestaticnoexcept

Definition at line 50 of file random.cpp.

Here is the caller graph for this function:

◆ GetRand()

uint64_t GetRand ( uint64_t nMax )

noexcept

Generate a uniform random integer in the range [0..range).

Precondition: range > 0

Definition at line 591 of file random.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ GetRandBytes()

void GetRandBytes	(	unsigned char *	buf,
		int	num
	)

noexcept

Overall design of the RNG and entropy sources.

We maintain a single global 256-bit RNG state for all high-quality randomness. The following (classes of) functions interact with that state by mixing in new entropy, and optionally extracting random output from it:

The GetRand*() class of functions, as well as construction of FastRandomContext objects, perform 'fast' seeding, consisting of mixing in:
- A stack pointer (indirectly committing to calling thread and call stack)
- A high-precision timestamp (rdtsc when available, c++ high_resolution_clock otherwise)
- 64 bits from the hardware RNG (rdrand) when available. These entropy sources are very fast, and only designed to protect against situations where a VM state restore/copy results in multiple systems with the same randomness. FastRandomContext on the other hand does not protect against this once created, but is even faster (and acceptable to use inside tight loops).
The GetStrongRand*() class of function perform 'slow' seeding, including everything that fast seeding includes, but additionally:
- OS entropy (/dev/urandom, getrandom(), ...). The application will terminate if this entropy source fails.
- Another high-precision timestamp (indirectly committing to a benchmark of all the previous sources). These entropy sources are slower, but designed to make sure the RNG state contains fresh data that is unpredictable to attackers.
RandAddPeriodic() seeds everything that fast seeding includes, but additionally:
- A high-precision timestamp
- Dynamic environment data (performance monitoring, ...)
- Strengthen the entropy for 10 ms using repeated SHA512. This is run once every minute.

On first use of the RNG (regardless of what function is called first), all entropy sources used in the 'slow' seeder are included, but also:

256 bits from the hardware RNG (rdseed or rdrand) when available.
Dynamic environment data (performance monitoring, ...)
Static environment data
Strengthen the entropy for 100 ms using repeated SHA512.

When mixing in new entropy, H = SHA512(entropy || old_rng_state) is computed, and (up to) the first 32 bytes of H are produced as output, while the last 32 bytes become the new RNG state. Generate random data via the internal PRNG.

These functions are designed to be fast (sub microsecond), but do not necessarily meaningfully add entropy to the PRNG state.

Thread-safe.

Definition at line 584 of file random.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ GetRandHash()

uint256 GetRandHash ( )

noexcept

Definition at line 601 of file random.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ GetRandInt()

int GetRandInt ( int nMax )

noexcept

Definition at line 596 of file random.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ GetStrongRandBytes()

void GetStrongRandBytes	(	unsigned char *	buf,
		int	num
	)

noexcept

Gather entropy from various sources, feed it into the internal PRNG, and generate random data using it.

This function will cause failure whenever the OS RNG fails.

Thread-safe.

Definition at line 585 of file random.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ InitHardwareRand()

static void InitHardwareRand ( )

static

Definition at line 184 of file random.cpp.

◆ ProcRand()

static void ProcRand	(	unsigned char *	out,
		int	num,
		RNGLevel	level
	)

staticnoexcept

Definition at line 555 of file random.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ RandAddEvent()

void RandAddEvent ( const uint32_t event_info )

noexcept

Gathers entropy from the low bits of the time at which events occur.

Should be called with a uint32_t describing the event at the time an event occurs.

Thread-safe.

Definition at line 587 of file random.cpp.

Here is the caller graph for this function:

◆ RandAddPeriodic()

void RandAddPeriodic ( )

noexcept

Gather entropy from various expensive sources, and feed them to the PRNG state.

Thread-safe.

Definition at line 586 of file random.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ RandFailure()

static void RandFailure ( )

static

Definition at line 44 of file random.cpp.

Here is the caller graph for this function:

◆ Random_SanityCheck()

bool Random_SanityCheck ( )

Check that OS randomness is available and returning the requested number of bytes.

Definition at line 641 of file random.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ RandomInit()

void RandomInit ( )

Initialize global RNG state and log any CPU features that are used.

Calling this function is optional. RNG state will be initialized when first needed if it is not called.

Definition at line 710 of file random.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ReportHardwareRand()

static void ReportHardwareRand ( )

static

Definition at line 185 of file random.cpp.

Here is the caller graph for this function:

◆ SeedFast()

static void SeedFast ( CSHA512 & hasher )

staticnoexcept

Definition at line 463 of file random.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ SeedHardwareFast()

static void SeedHardwareFast ( CSHA512 & hasher )

staticnoexcept

Add 64 bits of entropy gathered from hardware to hasher.

Do nothing if not supported.

Definition at line 189 of file random.cpp.

Here is the caller graph for this function:

◆ SeedHardwareSlow()

static void SeedHardwareSlow ( CSHA512 & hasher )

staticnoexcept

Add 256 bits of entropy gathered from hardware to hasher.

Do nothing if not supported.

Definition at line 200 of file random.cpp.

Here is the caller graph for this function:

◆ SeedPeriodic()

static void SeedPeriodic	(	CSHA512 &	hasher,
		RNGState &	rng
	)

staticnoexcept

Definition at line 509 of file random.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ SeedSlow()

static void SeedSlow	(	CSHA512 &	hasher,
		RNGState &	rng
	)

staticnoexcept

Definition at line 478 of file random.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ SeedStartup()

static void SeedStartup	(	CSHA512 &	hasher,
		RNGState &	rng
	)

staticnoexcept

Definition at line 529 of file random.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ SeedStrengthen()

static void SeedStrengthen	(	CSHA512 &	hasher,
		RNGState &	rng,
		int	microseconds
	)

staticnoexcept

Extract entropy from rng, strengthen it, and feed it into hasher.

Definition at line 500 of file random.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ SeedTimestamp()

static void SeedTimestamp ( CSHA512 & hasher )

staticnoexcept

Definition at line 457 of file random.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ Strengthen()

static void Strengthen	(	const unsigned char(&)	seed[32],
		int	microseconds,
		CSHA512 &	hasher
	)

staticnoexcept

Use repeated SHA512 to strengthen the randomness in seed32, and feed into hasher.

Definition at line 225 of file random.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

◆ g_mock_deterministic_tests

bool g_mock_deterministic_tests {false}

Flag to make GetRand in random.h return the same number.

Definition at line 589 of file random.cpp.

Enumerations

Functions

Variables

Enumeration Type Documentation

◆ RNGLevel

Function Documentation

◆ GetDevURandom()

◆ GetOSRand()

◆ GetPerformanceCounter()

◆ GetRand()

◆ GetRandBytes()

◆ GetRandHash()

◆ GetRandInt()

◆ GetStrongRandBytes()

◆ InitHardwareRand()

◆ ProcRand()

◆ RandAddEvent()

◆ RandAddPeriodic()

◆ RandFailure()

◆ Random_SanityCheck()

◆ RandomInit()

◆ ReportHardwareRand()

◆ SeedFast()

◆ SeedHardwareFast()

◆ SeedHardwareSlow()

◆ SeedPeriodic()

◆ SeedSlow()

◆ SeedStartup()

◆ SeedStrengthen()

◆ SeedTimestamp()

◆ Strengthen()

Variable Documentation

◆ g_mock_deterministic_tests