Botan  1.11.31
Public Member Functions | Static Public Member Functions | List of all members
Botan::RandomNumberGenerator Class Referenceabstract

#include <rng.h>

Inheritance diagram for Botan::RandomNumberGenerator:
Botan::ANSI_X931_RNG Botan::AutoSeeded_RNG Botan::Hardware_RNG Botan::Null_RNG Botan::Serialized_RNG Botan::Stateful_RNG Botan::System_RNG Botan::PKCS11::PKCS11_RNG Botan::RDRAND_RNG Botan::TPM_RNG Botan::HMAC_DRBG Botan::HMAC_RNG

Public Member Functions

virtual void add_entropy (const byte input[], size_t length)=0
 
template<typename T >
void add_entropy_T (const T &t)
 
virtual void clear ()=0
 
virtual bool is_seeded () const =0
 
virtual std::string name () const =0
 
byte next_byte ()
 
byte next_nonzero_byte ()
 
RandomNumberGeneratoroperator= (const RandomNumberGenerator &rng)=delete
 
secure_vector< byterandom_vec (size_t bytes)
 
virtual void randomize (byte output[], size_t length)=0
 
virtual void randomize_with_input (byte output[], size_t output_len, const byte input[], size_t input_len)
 
virtual void randomize_with_ts_input (byte output[], size_t output_len)
 
 RandomNumberGenerator ()=default
 
 RandomNumberGenerator (const RandomNumberGenerator &rng)=delete
 
virtual size_t reseed (Entropy_Sources &srcs, size_t poll_bits=BOTAN_RNG_RESEED_POLL_BITS, std::chrono::milliseconds poll_timeout=BOTAN_RNG_RESEED_DEFAULT_TIMEOUT)
 
virtual void reseed_from_rng (RandomNumberGenerator &rng, size_t poll_bits=BOTAN_RNG_RESEED_POLL_BITS)
 
virtual ~RandomNumberGenerator ()=default
 

Static Public Member Functions

static RandomNumberGeneratormake_rng ()
 

Detailed Description

An interface to a cryptographic random number generator

Definition at line 25 of file rng.h.

Constructor & Destructor Documentation

virtual Botan::RandomNumberGenerator::~RandomNumberGenerator ( )
virtualdefault
Botan::RandomNumberGenerator::RandomNumberGenerator ( )
default
Botan::RandomNumberGenerator::RandomNumberGenerator ( const RandomNumberGenerator rng)
delete

Member Function Documentation

virtual void Botan::RandomNumberGenerator::add_entropy ( const byte  input[],
size_t  length 
)
pure virtual

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
inputsa byte array containg the entropy to be added
lengththe length of the byte array in

Implemented in Botan::Serialized_RNG, Botan::Null_RNG, Botan::HMAC_DRBG, Botan::TPM_RNG, Botan::HMAC_RNG, Botan::AutoSeeded_RNG, and Botan::ANSI_X931_RNG.

Referenced by Botan::System_RNG::add_entropy(), Botan::NR_PrivateKey::check_key(), Botan::Stateful_RNG::initialize_with(), Botan::Darwin_SecRandom::poll(), Botan::Intel_Rdrand::poll(), Botan::Win32_CAPI_EntropySource::poll(), Botan::Device_EntropySource::poll(), Botan::EGD_EntropySource::poll(), Botan::Unix_EntropySource::poll(), Botan::ProcWalking_EntropySource::poll(), randomize_with_input(), and reseed_from_rng().

template<typename T >
void Botan::RandomNumberGenerator::add_entropy_T ( const T &  t)
inline

Incorporate some additional data into the RNG state.

Definition at line 60 of file rng.h.

Referenced by Botan::Win32_EntropySource::poll(), Botan::Intel_Rdseed::poll(), and Botan::UnixProcessInfo_EntropySource::poll().

61  {
62  this->add_entropy(reinterpret_cast<const uint8_t*>(&t), sizeof(T));
63  }
virtual void add_entropy(const byte input[], size_t length)=0
virtual void Botan::RandomNumberGenerator::clear ( )
pure virtual
virtual bool Botan::RandomNumberGenerator::is_seeded ( ) const
pure virtual

Check whether this RNG is seeded.

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

Implemented in Botan::Serialized_RNG, Botan::Null_RNG, Botan::TPM_RNG, Botan::Stateful_RNG, Botan::RDRAND_RNG, Botan::PKCS11::PKCS11_RNG, Botan::System_RNG, Botan::AutoSeeded_RNG, and Botan::ANSI_X931_RNG.

RandomNumberGenerator * Botan::RandomNumberGenerator::make_rng ( )
static

Create a seeded and active RNG object for general application use Added in 1.8.0 Use AutoSeeded_RNG instead

Definition at line 51 of file rng.cpp.

References Botan::Serialized_RNG::Serialized_RNG().

52  {
53 #if defined(BOTAN_HAS_AUTO_SEEDING_RNG)
54  return new AutoSeeded_RNG;
55 #else
56  throw Exception("make_rng failed, no AutoSeeded_RNG in this build");
57 #endif
58  }
virtual std::string Botan::RandomNumberGenerator::name ( ) const
pure virtual
byte Botan::RandomNumberGenerator::next_byte ( )
inline

Return a random byte

Returns
random byte

Definition at line 139 of file rng.h.

Referenced by Botan::Blinded_Point_Multiply::blinded_multiply(), and Botan::random_prime().

140  {
141  byte b;
142  this->randomize(&b, 1);
143  return b;
144  }
virtual void randomize(byte output[], size_t length)=0
std::uint8_t byte
Definition: types.h:31
byte Botan::RandomNumberGenerator::next_nonzero_byte ( )
inline

Definition at line 146 of file rng.h.

147  {
148  byte b = this->next_byte();
149  while(b == 0)
150  b = this->next_byte();
151  return b;
152  }
std::uint8_t byte
Definition: types.h:31
RandomNumberGenerator& Botan::RandomNumberGenerator::operator= ( const RandomNumberGenerator rng)
delete
secure_vector<byte> Botan::RandomNumberGenerator::random_vec ( size_t  bytes)
inline
virtual void Botan::RandomNumberGenerator::randomize ( byte  output[],
size_t  length 
)
pure virtual
void Botan::RandomNumberGenerator::randomize_with_input ( byte  output[],
size_t  output_len,
const byte  input[],
size_t  input_len 
)
virtual

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.

Reimplemented in Botan::HMAC_DRBG, and Botan::AutoSeeded_RNG.

Definition at line 30 of file rng.cpp.

References add_entropy(), and randomize().

Referenced by Botan::Stateful_RNG::randomize_with_ts_input(), and randomize_with_ts_input().

32  {
33  this->add_entropy(input, input_len);
34  this->randomize(output, output_len);
35  }
virtual void randomize(byte output[], size_t length)=0
virtual void add_entropy(const byte input[], size_t length)=0
void Botan::RandomNumberGenerator::randomize_with_ts_input ( byte  output[],
size_t  output_len 
)
virtual

This calls randomize_with_input using some timestamps as extra input.

For a stateful RNG using non-random but potentially unique data as the additional_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.

Reimplemented in Botan::Stateful_RNG.

Definition at line 17 of file rng.cpp.

References Botan::OS::get_processor_timestamp(), Botan::OS::get_system_timestamp_ns(), randomize_with_input(), and Botan::store_le().

Referenced by Botan::AutoSeeded_RNG::randomize().

18  {
19  /*
20  Form additional input which is provided to the PRNG implementation
21  to paramaterize the KDF output.
22  */
23  byte additional_input[16] = { 0 };
24  store_le(OS::get_system_timestamp_ns(), additional_input);
25  store_le(OS::get_processor_timestamp(), additional_input + 8);
26 
27  randomize_with_input(output, output_len, additional_input, sizeof(additional_input));
28  }
virtual void randomize_with_input(byte output[], size_t output_len, const byte input[], size_t input_len)
Definition: rng.cpp:30
void store_le(u16bit in, byte out[2])
Definition: loadstor.h:461
uint64_t get_processor_timestamp()
Definition: os_utils.cpp:41
uint64_t get_system_timestamp_ns()
Definition: os_utils.cpp:88
std::uint8_t byte
Definition: types.h:31
size_t Botan::RandomNumberGenerator::reseed ( Entropy_Sources srcs,
size_t  poll_bits = BOTAN_RNG_RESEED_POLL_BITS,
std::chrono::milliseconds  poll_timeout = BOTAN_RNG_RESEED_DEFAULT_TIMEOUT 
)
virtual

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

Reimplemented in Botan::Serialized_RNG, Botan::Stateful_RNG, Botan::HMAC_RNG, Botan::RDRAND_RNG, Botan::PKCS11::PKCS11_RNG, Botan::AutoSeeded_RNG, and Botan::ANSI_X931_RNG.

Definition at line 37 of file rng.cpp.

References Botan::Entropy_Sources::poll().

Referenced by Botan::Stateful_RNG::reseed().

40  {
41  return srcs.poll(*this, poll_bits, poll_timeout);
42  }
void Botan::RandomNumberGenerator::reseed_from_rng ( RandomNumberGenerator rng,
size_t  poll_bits = BOTAN_RNG_RESEED_POLL_BITS 
)
virtual

Reseed by reading specified bits from the RNG

Reimplemented in Botan::Stateful_RNG.

Definition at line 44 of file rng.cpp.

References add_entropy(), and randomize().

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

45  {
46  secure_vector<byte> buf(poll_bits / 8);
47  rng.randomize(buf.data(), buf.size());
48  this->add_entropy(buf.data(), buf.size());
49  }
virtual void add_entropy(const byte input[], size_t length)=0

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