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

#include <rdseed.h>

Inheritance diagram for Botan::Intel_Rdseed:
Botan::Entropy_Source

Public Member Functions

void gather (Entropy_Accumulator &acc) override
std::string name () const override
virtual size_t poll (RandomNumberGenerator &rng)

Static Public Member Functions

static std::unique_ptr< Entropy_Source > create (std::string_view type)

Detailed Description

Entropy source using the rdseed instruction first introduced on Intel's Broadwell architecture.

Definition at line 19 of file rdseed.h.

Member Function Documentation

◆ create()

std::unique_ptr< Entropy_Source > Botan::Entropy_Source::create ( std::string_view type)
staticinherited

Return a new entropy source of a particular type, or null Each entropy source may require substantial resources (eg, a file handle or socket instance), so try to share them among multiple RNGs, or just use the preconfigured global list accessed by Entropy_Sources::global_sources()

Definition at line 217 of file entropy_srcs.cpp.

217 {
218#if defined(BOTAN_HAS_SYSTEM_RNG)
219 if(name == "system_rng") {
220 return std::make_unique<System_RNG_EntropySource>();
221 }
222#endif
223
224#if defined(BOTAN_HAS_PROCESSOR_RNG)
225 if(name == "hwrng") {
227 return std::make_unique<Processor_RNG_EntropySource>();
228 }
229 }
230#endif
231
232#if defined(BOTAN_HAS_ENTROPY_SRC_RDSEED)
233 if(name == "rdseed") {
234 return std::make_unique<Intel_Rdseed>();
235 }
236#endif
237
238#if defined(BOTAN_HAS_ENTROPY_SRC_GETENTROPY)
239 if(name == "getentropy") {
240 return std::make_unique<Getentropy>();
241 }
242#endif
243
244#if defined(BOTAN_HAS_ENTROPY_SRC_WIN32)
245 if(name == "system_stats") {
246 return std::make_unique<Win32_EntropySource>();
247 }
248#endif
249
250#if defined(BOTAN_HAS_JITTER_RNG)
251 if(name == "jitter_rng") {
252 return std::make_unique<Jitter_RNG_EntropySource>(Jitter_RNG::Mode::Default);
253 }
254 if(name == "jitter_rng_fips") {
255 return std::make_unique<Jitter_RNG_EntropySource>(Jitter_RNG::Mode::FIPS);
256 }
257 if(name == "jitter_rng_ntg1") {
258 return std::make_unique<Jitter_RNG_EntropySource>(Jitter_RNG::Mode::NTG1);
259 }
260#endif
261
263 return nullptr;
264}
#define BOTAN_UNUSED
Definition assert.h:151
virtual std::string name() const =0
static bool available()

References Botan::Processor_RNG::available(), BOTAN_UNUSED, Botan::Jitter_RNG::Default, Botan::Jitter_RNG::FIPS, name(), and Botan::Jitter_RNG::NTG1.

Referenced by Botan::Entropy_Sources::Entropy_Sources().

◆ gather()

void Botan::Intel_Rdseed::gather ( Entropy_Accumulator & acc)
overridevirtual

Perform an entropy gathering poll

Contribute data to acc, each contribution along with a conservative estimate of the entropy it contains. Data which should be mixed in but not trusted is contributed with an estimate of zero. A source may stop early once acc.goal_reached() returns true.

Any implementation of this function should be thread safe; it may be called concurrently in multiple threads if multiple stateful RNGs reseed across different threads.

The default implementation exists only to support subclasses which implement the legacy poll interface, and forwards to poll.

Note that applications should not directly invoke this function to perform reseeding; use RandomNumberGenerator::reseed_from with an instance of Entropy_Sources which contains this source.

TODO(Botan4) make this a pure virtual

Reimplemented from Botan::Entropy_Source.

Definition at line 67 of file rdseed.cpp.

67 {
68 const size_t RDSEED_BYTES = 1024;
69 static_assert(RDSEED_BYTES % 4 == 0, "Bad RDSEED configuration");
70
73 seed.reserve(RDSEED_BYTES / 4);
74
75 for(size_t p = 0; p != RDSEED_BYTES / 4; ++p) {
76 /*
77 If at any point we exceed our retry count, we stop the entire seed
78 gathering process. This situation will only occur in situations of
79 extremely high RDSEED utilization. If RDSEED is currently so highly
80 contended, then the rest of the poll is likely to also face contention and
81 it is better to quit now rather than (presumably) face very high retry
82 times for the rest of the poll.
83 */
84 if(!read_rdseed(seed)) {
85 break;
86 }
87 }
88
89 if(!seed.empty()) {
90 // RDSEED is used but not trusted
91 acc.add(std::span(reinterpret_cast<const uint8_t*>(seed.data()), seed.size() * sizeof(uint32_t)), 0);
92 }
93 }
94}
static bool has(CPUID::Feature feat)
Definition cpuid.h:93
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:128

References Botan::Entropy_Accumulator::add(), Botan::CPUID::has(), and Botan::CPUFeature::RDSEED.

◆ name()

std::string Botan::Intel_Rdseed::name ( ) const
inlineoverridevirtual

Return a free-form string identifying this entropy source

Implements Botan::Entropy_Source.

Definition at line 21 of file rdseed.h.

21{ return "rdseed"; }

◆ poll()

size_t Botan::Entropy_Source::poll ( RandomNumberGenerator & rng)
virtualinherited

Perform an entropy gathering poll (legacy interface)

Parameters
Random Number Generatorswill be provided with entropy via calls to add_entropy
Returns
conservative estimate of actual entropy added to rng during poll

New sources should implement gather instead. The default implementation of this function forwards to gather.

TODO(Botan4) remove this function

Definition at line 206 of file entropy_srcs.cpp.

206 {
207 // A source implementing neither interface would otherwise recurse forever
208 if(dynamic_cast<Legacy_Poll_RNG*>(&rng) != nullptr) {
209 throw Not_Implemented(fmt("Entropy source {} does not implement gather", name()));
210 }
211
212 Entropy_Accumulator acc(RandomNumberGenerator::DefaultPollBits, additional_input_sink(rng));
213 this->gather(acc);
214 return acc.bits_collected();
215}
virtual void gather(Entropy_Accumulator &acc)
static constexpr size_t DefaultPollBits
Definition rng.h:50
std::string fmt(std::string_view format, const T &... args)
Definition fmt.h:53

References Botan::Entropy_Accumulator::bits_collected(), Botan::RandomNumberGenerator::DefaultPollBits, Botan::fmt(), gather(), and name().

Referenced by gather(), and name().


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