Botan 3.9.0
Crypto and TLS for C&
Botan::AutoSeeded_RNG Class Referencefinal

#include <auto_rng.h>

Inheritance diagram for Botan::AutoSeeded_RNG:
Botan::RandomNumberGenerator

Public Member Functions

bool accepts_input () const override
void add_entropy (const uint8_t input[], size_t length)
void add_entropy (std::span< const uint8_t > input)
template<typename T>
requires std::is_standard_layout_v<T> && std::is_trivial_v<T>
void add_entropy_T (const T &t)
 AutoSeeded_RNG (AutoSeeded_RNG &&other) noexcept
 AutoSeeded_RNG (const AutoSeeded_RNG &other)=delete
BOTAN_FUTURE_EXPLICIT AutoSeeded_RNG (Entropy_Sources &entropy_sources, size_t reseed_interval=RandomNumberGenerator::DefaultReseedInterval)
 AutoSeeded_RNG (RandomNumberGenerator &underlying_rng, Entropy_Sources &entropy_sources, size_t reseed_interval=RandomNumberGenerator::DefaultReseedInterval)
BOTAN_FUTURE_EXPLICIT AutoSeeded_RNG (RandomNumberGenerator &underlying_rng, size_t reseed_interval=RandomNumberGenerator::DefaultReseedInterval)
BOTAN_FUTURE_EXPLICIT AutoSeeded_RNG (size_t reseed_interval=RandomNumberGenerator::DefaultReseedInterval)
void clear () override
void force_reseed ()
bool is_seeded () const override
std::string name () const override
uint8_t next_byte ()
uint8_t next_nonzero_byte ()
AutoSeeded_RNGoperator= (AutoSeeded_RNG &&other)=delete
AutoSeeded_RNGoperator= (const AutoSeeded_RNG &other)=delete
template<size_t bytes>
std::array< uint8_t, bytes > random_array ()
template<concepts::resizable_byte_buffer T = secure_vector<uint8_t>>
requires std::default_initializable<T>
random_vec (size_t bytes)
void random_vec (std::span< uint8_t > v)
template<concepts::resizable_byte_buffer T>
void random_vec (T &v, size_t bytes)
void randomize (std::span< uint8_t > output)
void randomize (uint8_t output[], size_t length)
void randomize_with_input (std::span< uint8_t > output, std::span< const uint8_t > input)
void randomize_with_input (uint8_t output[], size_t output_len, const uint8_t input[], size_t input_len)
void randomize_with_ts_input (std::span< uint8_t > output)
void randomize_with_ts_input (uint8_t output[], size_t output_len)
size_t reseed (Entropy_Sources &srcs, size_t poll_bits=RandomNumberGenerator::DefaultPollBits, std::chrono::milliseconds poll_timeout=RandomNumberGenerator::DefaultPollTimeout) override
virtual void reseed_from_rng (RandomNumberGenerator &rng, size_t poll_bits=RandomNumberGenerator::DefaultPollBits)
 ~AutoSeeded_RNG () override

Static Public Attributes

static constexpr size_t DefaultPollBits = 256
static constexpr auto DefaultPollTimeout = std::chrono::milliseconds(50)
static constexpr size_t DefaultReseedInterval = 1024

Detailed Description

A userspace PRNG

Definition at line 22 of file auto_rng.h.

Constructor & Destructor Documentation

◆ AutoSeeded_RNG() [1/6]

Botan::AutoSeeded_RNG::AutoSeeded_RNG ( size_t reseed_interval = RandomNumberGenerator::DefaultReseedInterval)

Uses the system RNG (if available) or else a default group of entropy sources (all other systems) to gather seed material.

Parameters
reseed_intervalspecifies a limit of how many times the RNG will be called before automatic reseeding is performed

Definition at line 66 of file auto_rng.cpp.

66 {
67#if defined(BOTAN_HAS_SYSTEM_RNG)
68 m_rng = std::make_unique<HMAC_DRBG>(auto_rng_hmac(), system_rng(), reseed_interval);
69#elif defined(BOTAN_HAS_ENTROPY_SOURCE)
70 m_rng = std::make_unique<HMAC_DRBG>(auto_rng_hmac(), Entropy_Sources::global_sources(), reseed_interval);
71#else
72 BOTAN_UNUSED(reseed_interval);
73 throw Not_Implemented("AutoSeeded_RNG default constructor not available due to no RNG or entropy sources");
74#endif
75
77}
#define BOTAN_UNUSED
Definition assert.h:144
static Entropy_Sources & global_sources()
RandomNumberGenerator & system_rng()

References BOTAN_UNUSED, force_reseed(), Botan::Entropy_Sources::global_sources(), and Botan::system_rng().

Referenced by AutoSeeded_RNG(), AutoSeeded_RNG(), operator=(), and operator=().

◆ AutoSeeded_RNG() [2/6]

Botan::AutoSeeded_RNG::AutoSeeded_RNG ( RandomNumberGenerator & underlying_rng,
size_t reseed_interval = RandomNumberGenerator::DefaultReseedInterval )

Create an AutoSeeded_RNG which will get seed material from some other RNG instance. For example you could provide a reference to the system RNG or a hardware RNG.

Parameters
underlying_rngis a reference to some RNG which will be used to perform the periodic reseeding
reseed_intervalspecifies a limit of how many times the RNG will be called before automatic reseeding is performed

Definition at line 46 of file auto_rng.cpp.

46 {
47 m_rng = std::make_unique<HMAC_DRBG>(auto_rng_hmac(), underlying_rng, reseed_interval);
48
50}

References force_reseed(), and Botan::RandomNumberGenerator::RandomNumberGenerator().

◆ AutoSeeded_RNG() [3/6]

Botan::AutoSeeded_RNG::AutoSeeded_RNG ( Entropy_Sources & entropy_sources,
size_t reseed_interval = RandomNumberGenerator::DefaultReseedInterval )

Create an AutoSeeded_RNG which will get seed material from a set of entropy sources.

Parameters
entropy_sourceswill be polled to perform reseeding periodically
reseed_intervalspecifies a limit of how many times the RNG will be called before automatic reseeding is performed

Definition at line 52 of file auto_rng.cpp.

52 {
53 m_rng = std::make_unique<HMAC_DRBG>(auto_rng_hmac(), entropy_sources, reseed_interval);
54
56}

References force_reseed().

◆ AutoSeeded_RNG() [4/6]

Botan::AutoSeeded_RNG::AutoSeeded_RNG ( RandomNumberGenerator & underlying_rng,
Entropy_Sources & entropy_sources,
size_t reseed_interval = RandomNumberGenerator::DefaultReseedInterval )

Create an AutoSeeded_RNG which will get seed material from both an underlying RNG and a set of entropy sources.

Parameters
underlying_rngis a reference to some RNG which will be used to perform the periodic reseeding
entropy_sourceswill be polled to perform reseeding periodically
reseed_intervalspecifies a limit of how many times the RNG will be called before automatic reseeding is performed

Definition at line 58 of file auto_rng.cpp.

60 {
61 m_rng = std::make_unique<HMAC_DRBG>(auto_rng_hmac(), underlying_rng, entropy_sources, reseed_interval);
62
64}

References force_reseed(), and Botan::RandomNumberGenerator::RandomNumberGenerator().

◆ AutoSeeded_RNG() [5/6]

Botan::AutoSeeded_RNG::AutoSeeded_RNG ( const AutoSeeded_RNG & other)
delete

References AutoSeeded_RNG().

◆ AutoSeeded_RNG() [6/6]

Botan::AutoSeeded_RNG::AutoSeeded_RNG ( AutoSeeded_RNG && other)
defaultnoexcept

References AutoSeeded_RNG().

◆ ~AutoSeeded_RNG()

Botan::AutoSeeded_RNG::~AutoSeeded_RNG ( )
overridedefault

Member Function Documentation

◆ accepts_input()

bool Botan::AutoSeeded_RNG::accepts_input ( ) const
inlineoverridevirtual

Returns false if it is known that this RNG object is not able to accept externally provided inputs (via add_entropy, randomize_with_input, etc). In this case, any such provided inputs are ignored.

If this function returns true, then inputs may or may not be accepted.

Implements Botan::RandomNumberGenerator.

Definition at line 26 of file auto_rng.h.

26{ return true; }

◆ add_entropy() [1/2]

void Botan::RandomNumberGenerator::add_entropy ( const uint8_t input[],
size_t length )
inlineinherited

Definition at line 96 of file rng.h.

96{ this->add_entropy(std::span(input, length)); }
void add_entropy(std::span< const uint8_t > input)
Definition rng.h:94

References add_entropy().

Referenced by add_entropy().

◆ add_entropy() [2/2]

void Botan::RandomNumberGenerator::add_entropy ( std::span< const uint8_t > input)
inlineinherited

Incorporate some additional data into the RNG state. For example adding nonces or timestamps from a peer's protocol message can help hedge against VM state rollback attacks. A few RNG types do not accept any externally provided input, in which case this function is a no-op.

Parameters
inputa byte array containing the entropy to be added
Exceptions
Exceptionmay throw if the RNG accepts input, but adding the entropy failed.

Definition at line 94 of file rng.h.

94{ this->fill_bytes_with_input({}, input); }
virtual void fill_bytes_with_input(std::span< uint8_t > output, std::span< const uint8_t > input)=0

References fill_bytes_with_input().

Referenced by add_entropy_T(), Botan::ChaCha_RNG::ChaCha_RNG(), Botan::Stateful_RNG::initialize_with(), Botan::Getentropy::poll(), Botan::Intel_Rdseed::poll(), and reseed_from_rng().

◆ add_entropy_T()

template<typename T>
requires std::is_standard_layout_v<T> && std::is_trivial_v<T>
void Botan::RandomNumberGenerator::add_entropy_T ( const T & t)
inlineinherited

Incorporate some additional data into the RNG state.

Definition at line 103 of file rng.h.

103 {
104 this->add_entropy(reinterpret_cast<const uint8_t*>(&t), sizeof(T));
105 }

References add_entropy().

Referenced by Botan::Win32_EntropySource::poll().

◆ clear()

void Botan::AutoSeeded_RNG::clear ( )
overridevirtual

Clear all internally held values of this RNG

Postcondition
is_seeded() == false if the RNG has an internal state that can be cleared.

Implements Botan::RandomNumberGenerator.

Definition at line 92 of file auto_rng.cpp.

92 {
93 m_rng->clear();
94}

◆ force_reseed()

void Botan::AutoSeeded_RNG::force_reseed ( )

Mark state as requiring a reseed on next use

Definition at line 79 of file auto_rng.cpp.

79 {
80 m_rng->force_reseed();
81 m_rng->next_byte();
82
83 if(!m_rng->is_seeded()) {
84 throw Internal_Error("AutoSeeded_RNG reseeding failed");
85 }
86}

Referenced by AutoSeeded_RNG(), AutoSeeded_RNG(), AutoSeeded_RNG(), and AutoSeeded_RNG().

◆ is_seeded()

bool Botan::AutoSeeded_RNG::is_seeded ( ) const
overridevirtual

Check whether this RNG is seeded.

Returns
true if this RNG was already seeded, false otherwise.

Implements Botan::RandomNumberGenerator.

Definition at line 88 of file auto_rng.cpp.

88 {
89 return m_rng->is_seeded();
90}

◆ name()

std::string Botan::AutoSeeded_RNG::name ( ) const
overridevirtual
Returns
the name of this RNG type

Implements Botan::RandomNumberGenerator.

Definition at line 96 of file auto_rng.cpp.

96 {
97 return m_rng->name();
98}

◆ next_byte()

uint8_t Botan::RandomNumberGenerator::next_byte ( )
inlineinherited

Return a random byte

Returns
random byte
Exceptions
PRNG_Unseededif the RNG fails because it has not enough entropy
Exceptionif the RNG fails

Definition at line 247 of file rng.h.

247 {
248 uint8_t b = 0;
249 this->fill_bytes_with_input(std::span(&b, 1), {});
250 return b;
251 }

References fill_bytes_with_input().

Referenced by next_nonzero_byte(), and Botan::random_prime().

◆ next_nonzero_byte()

uint8_t Botan::RandomNumberGenerator::next_nonzero_byte ( )
inlineinherited
Returns
a random byte that is greater than zero
Exceptions
PRNG_Unseededif the RNG fails because it has not enough entropy
Exceptionif the RNG fails

Definition at line 258 of file rng.h.

258 {
259 uint8_t b = this->next_byte();
260 while(b == 0) {
261 b = this->next_byte();
262 }
263 return b;
264 }

References next_byte().

◆ operator=() [1/2]

AutoSeeded_RNG & Botan::AutoSeeded_RNG::operator= ( AutoSeeded_RNG && other)
delete

References AutoSeeded_RNG().

◆ operator=() [2/2]

AutoSeeded_RNG & Botan::AutoSeeded_RNG::operator= ( const AutoSeeded_RNG & other)
delete

References AutoSeeded_RNG().

◆ random_array()

template<size_t bytes>
std::array< uint8_t, bytes > Botan::RandomNumberGenerator::random_array ( )
inlineinherited

Create a std::array of bytes random bytes

Definition at line 235 of file rng.h.

235 {
236 std::array<uint8_t, bytes> result{};
237 random_vec(result);
238 return result;
239 }
void random_vec(std::span< uint8_t > v)
Definition rng.h:199

References random_vec().

◆ random_vec() [1/3]

template<concepts::resizable_byte_buffer T = secure_vector<uint8_t>>
requires std::default_initializable<T>
T Botan::RandomNumberGenerator::random_vec ( size_t bytes)
inlineinherited

Create some byte container type and fill it with some random bytes.

Template Parameters
Tthe desired byte container type (e.g std::vector<uint8_t>)
Parameters
bytesnumber of random bytes to initialize the container with
Returns
a container of type T with bytes random bytes
Exceptions
Exceptionif RNG or memory allocation fails

Definition at line 225 of file rng.h.

225 {
226 T result;
227 random_vec(result, bytes);
228 return result;
229 }

References random_vec().

◆ random_vec() [2/3]

◆ random_vec() [3/3]

template<concepts::resizable_byte_buffer T>
void Botan::RandomNumberGenerator::random_vec ( T & v,
size_t bytes )
inlineinherited

Resize a given byte container to bytes and fill it with random bytes

Template Parameters
Tthe desired byte container type (e.g std::vector<uint8_t>)
Parameters
vthe container to be filled with bytes random bytes
bytesnumber of random bytes to initialize the container with
Exceptions
Exceptionif RNG or memory allocation fails

Definition at line 210 of file rng.h.

210 {
211 v.resize(bytes);
212 random_vec(v);
213 }

References random_vec().

◆ randomize() [1/2]

void Botan::RandomNumberGenerator::randomize ( std::span< uint8_t > output)
inlineinherited

◆ randomize() [2/2]

void Botan::RandomNumberGenerator::randomize ( uint8_t output[],
size_t length )
inlineinherited

Definition at line 73 of file rng.h.

73{ this->randomize(std::span(output, length)); }

References randomize().

Referenced by randomize().

◆ randomize_with_input() [1/2]

void Botan::RandomNumberGenerator::randomize_with_input ( std::span< uint8_t > output,
std::span< const uint8_t > input )
inlineinherited

Incorporate entropy into the RNG state then produce output. Some RNG types implement this using a single operation, default calls add_entropy + randomize in sequence.

Use this to further bind the outputs to your current process/protocol state. For instance if generating a new key for use in a session, include a session ID or other such value. See NIST SP 800-90 A, B, C series for more ideas.

Parameters
outputbuffer to hold the random output
inputentropy buffer to incorporate
Exceptions
PRNG_Unseededif the RNG fails because it has not enough entropy
Exceptionif the RNG fails
Exceptionmay throw if the RNG accepts input, but adding the entropy failed.

Definition at line 123 of file rng.h.

123 {
124 this->fill_bytes_with_input(output, input);
125 }

References fill_bytes_with_input().

Referenced by Botan::System_RNG::fill_bytes_with_input(), and randomize_with_input().

◆ randomize_with_input() [2/2]

void Botan::RandomNumberGenerator::randomize_with_input ( uint8_t output[],
size_t output_len,
const uint8_t input[],
size_t input_len )
inlineinherited

Definition at line 127 of file rng.h.

127 {
128 this->randomize_with_input(std::span(output, output_len), std::span(input, input_len));
129 }
void randomize_with_input(std::span< uint8_t > output, std::span< const uint8_t > input)
Definition rng.h:123

References randomize_with_input().

◆ randomize_with_ts_input() [1/2]

void Botan::RandomNumberGenerator::randomize_with_ts_input ( std::span< uint8_t > output)
inherited

This calls randomize_with_input using some timestamps as extra input.

For a stateful RNG using non-random but potentially unique data the extra input can help protect against problems with fork, VM state rollback, or other cases where somehow an RNG state is duplicated. If both of the duplicated RNG states later incorporate a timestamp (and the timestamps don't themselves repeat), their outputs will diverge.

Parameters
outputbuffer to hold the random output
Exceptions
PRNG_Unseededif the RNG fails because it has not enough entropy
Exceptionif the RNG fails
Exceptionmay throw if the RNG accepts input, but adding the entropy failed.

Definition at line 27 of file rng.cpp.

27 {
28 if(this->accepts_input()) {
29 std::array<uint8_t, 32> additional_input = {0};
30
31#if defined(BOTAN_HAS_OS_UTILS)
32 store_le(std::span{additional_input}.subspan<0, 8>(), OS::get_high_resolution_clock());
33 store_le(std::span{additional_input}.subspan<8, 4>(), OS::get_process_id());
34 constexpr size_t offset = 12;
35#else
36 constexpr size_t offset = 0;
37#endif
38
39#if defined(BOTAN_HAS_SYSTEM_RNG)
40 system_rng().randomize(std::span{additional_input}.subspan<offset>());
41#else
42 BOTAN_UNUSED(offset);
43#endif
44
45 this->fill_bytes_with_input(output, additional_input);
46 } else {
47 this->fill_bytes_with_input(output, {});
48 }
49}
virtual bool accepts_input() const =0
uint64_t BOTAN_TEST_API get_high_resolution_clock()
Definition os_utils.cpp:268
uint32_t BOTAN_TEST_API get_process_id()
Definition os_utils.cpp:77
constexpr auto store_le(ParamTs &&... params)
Definition loadstor.h:736

References accepts_input(), BOTAN_UNUSED, fill_bytes_with_input(), Botan::OS::get_high_resolution_clock(), Botan::OS::get_process_id(), randomize(), Botan::store_le(), and Botan::system_rng().

Referenced by randomize_with_ts_input().

◆ randomize_with_ts_input() [2/2]

void Botan::RandomNumberGenerator::randomize_with_ts_input ( uint8_t output[],
size_t output_len )
inlineinherited

Definition at line 147 of file rng.h.

147 {
148 this->randomize_with_ts_input(std::span(output, output_len));
149 }
void randomize_with_ts_input(std::span< uint8_t > output)
Definition rng.cpp:27

References randomize_with_ts_input().

◆ reseed()

size_t Botan::AutoSeeded_RNG::reseed ( Entropy_Sources & srcs,
size_t poll_bits = RandomNumberGenerator::DefaultPollBits,
std::chrono::milliseconds poll_timeout = RandomNumberGenerator::DefaultPollTimeout )
overridevirtual

Poll provided sources for up to poll_bits bits of entropy or until the timeout expires. Returns estimate of the number of bits collected.

Sets the seeded state to true if enough entropy was added.

Reimplemented from Botan::RandomNumberGenerator.

Definition at line 100 of file auto_rng.cpp.

100 {
101 return m_rng->reseed(srcs, poll_bits, poll_timeout);
102}

◆ reseed_from_rng()

void Botan::RandomNumberGenerator::reseed_from_rng ( RandomNumberGenerator & rng,
size_t poll_bits = RandomNumberGenerator::DefaultPollBits )
virtualinherited

Reseed by reading specified bits from the RNG

Sets the seeded state to true if enough entropy was added.

Exceptions
Exceptionif RNG accepts input but reseeding failed.

Reimplemented in Botan::Stateful_RNG.

Definition at line 63 of file rng.cpp.

63 {
64 if(this->accepts_input()) {
65 this->add_entropy(rng.random_vec(poll_bits / 8));
66 }
67}

References accepts_input(), add_entropy(), random_vec(), and RandomNumberGenerator().

Referenced by is_seeded(), and Botan::Stateful_RNG::reseed_from_rng().

Member Data Documentation

◆ DefaultPollBits

size_t Botan::RandomNumberGenerator::DefaultPollBits = 256
staticconstexprinherited

Number of entropy bits polled for reseeding userspace RNGs like HMAC_DRBG

Definition at line 41 of file rng.h.

Referenced by is_seeded().

◆ DefaultPollTimeout

auto Botan::RandomNumberGenerator::DefaultPollTimeout = std::chrono::milliseconds(50)
staticconstexprinherited

Default poll timeout

Definition at line 46 of file rng.h.

Referenced by is_seeded().

◆ DefaultReseedInterval

size_t Botan::RandomNumberGenerator::DefaultReseedInterval = 1024
staticconstexprinherited

Userspace RNGs like HMAC_DRBG will reseed after a specified number of outputs are generated. Set to zero to disable automatic reseeding.

Definition at line 36 of file rng.h.


The documentation for this class was generated from the following files: