Bitcoin Core  0.18.99
P2P Digital Currency
Enumerations | Functions | Variables
random.cpp File Reference
#include <random.h>
#include <crypto/sha512.h>
#include <support/cleanse.h>
#include <logging.h>
#include <sync.h>
#include <util/time.h>
#include <stdlib.h>
#include <chrono>
#include <thread>
#include <support/allocators/secure.h>
#include <fcntl.h>
#include <sys/time.h>
#include <mutex>
#include <openssl/err.h>
#include <openssl/rand.h>
#include <openssl/conf.h>
Include dependency graph for random.cpp:

Go to the source code of this file.

Enumerations

enum  RNGLevel { RNGLevel::FAST, RNGLevel::SLOW, RNGLevel::SLEEP }
 

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 RandAddSeedPerfmon (CSHA512 &hasher)
 
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...
 
void LockingCallbackOpenSSL (int mode, int i, const char *file, int line)
 
static void SeedTimestamp (CSHA512 &hasher) noexcept
 
static void SeedFast (CSHA512 &hasher) noexcept
 
static void SeedSlow (CSHA512 &hasher) noexcept
 
static void SeedStrengthen (CSHA512 &hasher, RNGState &rng) noexcept
 Extract entropy from rng, strengthen it, and feed it into hasher. More...
 
static void SeedSleep (CSHA512 &hasher, RNGState &rng)
 
static void SeedStartup (CSHA512 &hasher, RNGState &rng) noexcept
 
static void ProcRand (unsigned char *out, int num, RNGLevel level)
 
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 RandAddSeedSleep ()
 Sleep for 1ms, gather entropy from various sources, and feed them to the PRNG state. More...
 
uint64_t GetRand (uint64_t nMax) noexcept
 
std::chrono::microseconds GetRandMicros (std::chrono::microseconds duration_max) noexcept
 
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}
 

Enumeration Type Documentation

◆ RNGLevel

enum RNGLevel
strong
Enumerator
FAST 

Automatically called by GetRandBytes.

SLOW 

Automatically called by GetStrongRandBytes.

SLEEP 

Called by RandAddSeedSleep()

Definition at line 616 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 310 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.

Definition at line 330 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 60 of file random.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ GetRand()

uint64_t GetRand ( uint64_t  nMax)
noexcept

Definition at line 665 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.
    • Bytes from OpenSSL's RNG (which itself may be seeded from various sources)
    • 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.
  • RandAddSeedSleep() seeds everything that fast seeding includes, but additionally:
    • A high-precision timestamp before and after sleeping 1ms.
    • (On Windows) Once every 10 minutes, performance monitoring data from the OS.

- Once every minute, strengthen the entropy for 10 ms using repeated SHA512. These just exploit the fact the system is idle to improve the quality of the RNG slightly.

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.
  • (On Windows) Performance monitoring data from the OS.
  • (On Windows) Through OpenSSL, the screen contents.
  • 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 659 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 680 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 675 of file random.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ GetRandMicros()

std::chrono::microseconds GetRandMicros ( std::chrono::microseconds  duration_max)
noexcept

Definition at line 670 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 660 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 200 of file random.cpp.

Here is the caller graph for this function:

◆ LockingCallbackOpenSSL()

void LockingCallbackOpenSSL ( int  mode,
int  i,
const char *  file,
int  line 
)

Definition at line 491 of file random.cpp.

Here is the caller graph for this function:

◆ ProcRand()

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

Definition at line 622 of file random.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ RandAddSeedPerfmon()

static void RandAddSeedPerfmon ( CSHA512 hasher)
static

Definition at line 268 of file random.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ RandAddSeedSleep()

void RandAddSeedSleep ( )

Sleep for 1ms, gather entropy from various sources, and feed them to the PRNG state.

Thread-safe.

Definition at line 661 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 54 of file random.cpp.

Here is the call graph for this function:
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 720 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 789 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 201 of file random.cpp.

Here is the caller graph for this function:

◆ SeedFast()

static void SeedFast ( CSHA512 hasher)
staticnoexcept

Definition at line 523 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 205 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 216 of file random.cpp.

Here is the caller graph for this function:

◆ SeedSleep()

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

Definition at line 576 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)
staticnoexcept

Definition at line 538 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 597 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 
)
staticnoexcept

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

Definition at line 561 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 517 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 241 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}

Definition at line 663 of file random.cpp.