Botan 3.14.1
Crypto and TLS for C&
Botan::Entropy_Sources Class Referencefinal

#include <entropy_src.h>

Public Member Functions

size_t _gather (Entropy_Accumulator &acc)
size_t _gather_just (Entropy_Accumulator &acc, std::string_view src)
void add_source (std::unique_ptr< Entropy_Source > src)
std::vector< std::string > enabled_sources () const
 Entropy_Sources ()=default
 Entropy_Sources (const Entropy_Sources &other)=delete
 Entropy_Sources (const std::vector< std::string > &sources)
 Entropy_Sources (Entropy_Sources &&other)=delete
Entropy_Sources & operator= (const Entropy_Sources &other)=delete
Entropy_Sources & operator= (Entropy_Sources &&other)=delete
size_t poll (RandomNumberGenerator &rng, size_t bits)
size_t poll (RandomNumberGenerator &rng, size_t bits, std::chrono::milliseconds timeout)
size_t poll_just (RandomNumberGenerator &rng, std::string_view src)
 ~Entropy_Sources ()=default

Static Public Member Functions

static Entropy_Sources & global_sources ()

Detailed Description

A collection of entropy sources which can be polled together

Definition at line 167 of file entropy_src.h.

Constructor & Destructor Documentation

◆ Entropy_Sources() [1/4]

Botan::Entropy_Sources::Entropy_Sources ( )
default

Create an empty collection of entropy sources

References Entropy_Sources().

Referenced by Entropy_Sources(), Entropy_Sources(), Entropy_Sources(), global_sources(), operator=(), and operator=().

◆ Entropy_Sources() [2/4]

Botan::Entropy_Sources::Entropy_Sources ( const std::vector< std::string > & sources)
explicit

Create a collection containing the named entropy sources

Parameters
sourcesthe names of the sources to enable

Definition at line 341 of file entropy_srcs.cpp.

341 {
342 for(auto&& src_name : sources) {
344 }
345}
static std::unique_ptr< Entropy_Source > create(std::string_view type)
void add_source(std::unique_ptr< Entropy_Source > src)

References add_source(), and Botan::Entropy_Source::create().

◆ Entropy_Sources() [3/4]

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

References Entropy_Sources().

◆ Entropy_Sources() [4/4]

Botan::Entropy_Sources::Entropy_Sources ( Entropy_Sources && other)
delete

References Entropy_Sources().

◆ ~Entropy_Sources()

Botan::Entropy_Sources::~Entropy_Sources ( )
default

Member Function Documentation

◆ _gather()

size_t Botan::Entropy_Sources::_gather ( Entropy_Accumulator & acc)

Poll all sources into acc until its goal is reached

This should not be called by applications and is not covered by SemVer

Returns
the number of bits collected during this call

Definition at line 281 of file entropy_srcs.cpp.

281 {
282 const size_t bits_before = acc.bits_collected();
283
284 for(auto& src : m_srcs) {
285 if(acc.goal_reached()) {
286 break;
287 }
288
289 src->gather(acc);
290 }
291
292 return acc.bits_collected() - bits_before;
293}

References Botan::Entropy_Accumulator::bits_collected(), and Botan::Entropy_Accumulator::goal_reached().

Referenced by poll(), Botan::RandomNumberGenerator::reseed_from_sources(), and Botan::Stateful_RNG::reseed_from_sources().

◆ _gather_just()

size_t Botan::Entropy_Sources::_gather_just ( Entropy_Accumulator & acc,
std::string_view src )

Poll just a single named source into acc. Ordinally only used for testing

This should not be called by applications and is not covered by SemVer

Returns
the number of bits collected during this call, or zero if no source with this name exists

Definition at line 295 of file entropy_srcs.cpp.

295 {
296 for(auto& src : m_srcs) {
297 if(src->name() == the_src) {
298 const size_t bits_before = acc.bits_collected();
299 src->gather(acc);
300 return acc.bits_collected() - bits_before;
301 }
302 }
303
304 return 0;
305}

References Botan::Entropy_Accumulator::bits_collected().

Referenced by poll_just().

◆ add_source()

void Botan::Entropy_Sources::add_source ( std::unique_ptr< Entropy_Source > src)

Add an entropy source to this collection

Parameters
srcthe source to add

Definition at line 266 of file entropy_srcs.cpp.

266 {
267 if(src) {
268 m_srcs.push_back(std::move(src));
269 }
270}

Referenced by Entropy_Sources().

◆ enabled_sources()

std::vector< std::string > Botan::Entropy_Sources::enabled_sources ( ) const

List the entropy sources in this collection

Returns
the names of the enabled sources

Definition at line 272 of file entropy_srcs.cpp.

272 {
273 std::vector<std::string> sources;
274 sources.reserve(m_srcs.size());
275 for(const auto& src : m_srcs) {
276 sources.push_back(src->name());
277 }
278 return sources;
279}

◆ global_sources()

Entropy_Sources & Botan::Entropy_Sources::global_sources ( )
static

Access the process-wide set of entropy sources used by default

Warning
This object is not synchronized. For general usage (eg polling) this is fine. However if you use global_sources().add_source() concurrently with a poll, likely a race leading to memory corruption will occur; only add a new entropy source at the start of main before RNG objects are created.

Definition at line 347 of file entropy_srcs.cpp.

347 {
348 static Entropy_Sources global_entropy_sources({"rdseed", "hwrng", "getentropy", "system_rng", "system_stats"});
349
350 return global_entropy_sources;
351}

References Entropy_Sources().

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

◆ operator=() [1/2]

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

References Entropy_Sources().

◆ operator=() [2/2]

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

References Entropy_Sources().

◆ poll() [1/2]

size_t Botan::Entropy_Sources::poll ( RandomNumberGenerator & rng,
size_t bits )

Poll all sources to collect bits of entropy. Entropy collection is aborted as soon as the requested number of bits are obtained.

The data is mixed into rng without affecting its seeded state. To seed an RNG from entropy sources use RandomNumberGenerator::reseed_from

Returns
the number of bits collected from the entropy sources

Definition at line 331 of file entropy_srcs.cpp.

331 {
332 Entropy_Accumulator acc(poll_bits, additional_input_sink(rng));
333 return this->_gather(acc);
334}
size_t _gather(Entropy_Accumulator &acc)

References _gather().

◆ poll() [2/2]

size_t Botan::Entropy_Sources::poll ( RandomNumberGenerator & rng,
size_t bits,
std::chrono::milliseconds timeout )

Poll all sources to collect bits of entropy with a timeout. Entropy collection is aborted as soon as either the requested number of bits are obtained or the timeout runs out. If the target system does not provide a clock, the timeout is ignored.

Note that the timeout is cooperative. If the poll() method of an entropy source blocks forever, this invocation will potentially also block.

Returns
the number of bits collected from the entropy sources

TODO(Botan4) remove this variant, and the <chrono> include above

Definition at line 307 of file entropy_srcs.cpp.

307 {
308#if defined(BOTAN_TARGET_OS_HAS_SYSTEM_CLOCK)
309 typedef std::chrono::steady_clock clock;
310 // Compare elapsed time in milliseconds to avoid overflow for very large timeouts
311 const auto timeout_expired = [start = clock::now(), timeout] {
312 return std::chrono::duration_cast<std::chrono::milliseconds>(clock::now() - start) > timeout;
313 };
314#else
315 auto timeout_expired = [] { return false; };
316#endif
317
318 Entropy_Accumulator acc(poll_bits, additional_input_sink(rng));
319
320 for(auto& src : m_srcs) {
321 src->gather(acc);
322
323 if(acc.goal_reached() || timeout_expired()) {
324 break;
325 }
326 }
327
328 return acc.bits_collected();
329}

References Botan::Entropy_Accumulator::bits_collected(), and Botan::Entropy_Accumulator::goal_reached().

◆ poll_just()

size_t Botan::Entropy_Sources::poll_just ( RandomNumberGenerator & rng,
std::string_view src )

Poll just a single named source. Ordinally only used for testing

The data is mixed into rng without affecting its seeded state.

Definition at line 336 of file entropy_srcs.cpp.

336 {
337 Entropy_Accumulator acc(RandomNumberGenerator::DefaultPollBits, additional_input_sink(rng));
338 return this->_gather_just(acc, the_src);
339}
size_t _gather_just(Entropy_Accumulator &acc, std::string_view src)
static constexpr size_t DefaultPollBits
Definition rng.h:50

References _gather_just(), and Botan::RandomNumberGenerator::DefaultPollBits.


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