Botan 3.14.1
Crypto and TLS for C&
entropy_srcs.cpp
Go to the documentation of this file.
1/*
2* Entropy Source Polling
3* (C) 2008-2010,2015 Jack Lloyd
4*
5* Botan is released under the Simplified BSD License (see license.txt)
6*/
7
8#include <botan/entropy_src.h>
9
10#include <botan/assert.h>
11#include <botan/exceptn.h>
12#include <botan/rng.h>
13#include <botan/internal/fmt.h>
14#include <botan/internal/target_info.h>
15#include <algorithm>
16
17#if defined(BOTAN_HAS_SYSTEM_RNG)
18 #include <botan/system_rng.h>
19#endif
20
21#if defined(BOTAN_HAS_PROCESSOR_RNG)
22 #include <botan/processor_rng.h>
23#endif
24
25#if defined(BOTAN_HAS_ENTROPY_SRC_RDSEED)
26 #include <botan/internal/rdseed.h>
27#endif
28
29#if defined(BOTAN_HAS_ENTROPY_SRC_WIN32)
30 #include <botan/internal/es_win32.h>
31#endif
32
33#if defined(BOTAN_HAS_ENTROPY_SRC_GETENTROPY)
34 #include <botan/internal/getentropy.h>
35#endif
36
37#if defined(BOTAN_HAS_JITTER_RNG)
38 #include <botan/jitter_rng.h>
39#endif
40
41namespace Botan {
42
43namespace {
44
45/*
46* Stand-in RNG handed to sources which implement the legacy
47* Entropy_Source::poll interface. It forwards any input to the accumulator
48* and refuses to produce output, so the source cannot affect the RNG which
49* is actually being seeded.
50*
51* TODO(Botan4) this can be removed when Entropy_Source::poll is
52*/
53class Legacy_Poll_RNG final : public RandomNumberGenerator {
54 public:
55 explicit Legacy_Poll_RNG(Entropy_Accumulator& acc) : m_acc(acc) {}
56
57 bool accepts_input() const override { return true; }
58
59 bool is_seeded() const override { return false; }
60
61 void clear() override {}
62
63 std::string name() const override { return "Legacy_Poll_RNG"; }
64
65 private:
66 void fill_bytes_with_input(std::span<uint8_t> output, std::span<const uint8_t> input) override {
67 if(!output.empty()) {
68 throw Invalid_State("An entropy source cannot draw output from the RNG being seeded");
69 }
70 // Credit is assigned from the return value of poll once it completes
71 m_acc.add(input, 0);
72 }
73
74 Entropy_Accumulator& m_acc;
75};
76
77Entropy_Accumulator::Sink additional_input_sink(RandomNumberGenerator& rng) {
78 return [&rng](std::span<const uint8_t> in) { rng.randomize_with_input({}, in); };
79}
80
81#if defined(BOTAN_HAS_SYSTEM_RNG) || defined(BOTAN_HAS_PROCESSOR_RNG) || defined(BOTAN_HAS_JITTER_RNG)
82
83class RNG_Based_EntropySource : public Entropy_Source {
84 public:
85 void gather(Entropy_Accumulator& acc) final;
86
87 protected:
88 virtual size_t poll_bits() const { return RandomNumberGenerator::DefaultPollBits; }
89
90 virtual bool trusted() const { return true; }
91
92 virtual RandomNumberGenerator& rng() = 0;
93};
94
95void RNG_Based_EntropySource::gather(Entropy_Accumulator& acc) {
96 secure_vector<uint8_t> buf(poll_bits() / 8);
97 try {
98 rng().randomize(buf);
99 } catch(...) {
100 /* ignore all errors from the RNG and simply return */
101 return;
102 }
103
104 const size_t estimated_entropy_bits = trusted() ? (buf.size() * 8) : (0);
105 acc.add(buf, estimated_entropy_bits);
106}
107
108#endif
109
110#if defined(BOTAN_HAS_SYSTEM_RNG)
111
112class System_RNG_EntropySource final : public RNG_Based_EntropySource {
113 public:
114 std::string name() const override { return "system_rng"; }
115
116 RandomNumberGenerator& rng() override { return system_rng(); }
117};
118
119#endif
120
121#if defined(BOTAN_HAS_PROCESSOR_RNG)
122
123class Processor_RNG_EntropySource final : public RNG_Based_EntropySource {
124 public:
125 size_t poll_bits() const override {
126 /*
127 * Intel's documentation for RDRAND at
128 * https://software.intel.com/en-us/articles/intel-digital-random-number-generator-drng-software-implementation-guide
129 * claims that software can guarantee a reseed event by polling enough data:
130 * "There is an upper bound of 511 samples per seed in the implementation
131 * where samples are 128 bits in size and can provide two 64-bit random
132 * numbers each."
133 *
134 * By requesting 65536 bits we are asking for 512 samples and thus are assured
135 * that at some point in producing the output, at least one reseed of the
136 * internal state will occur.
137 *
138 * The reseeding conditions of the POWER and ARM processor RNGs are not known
139 * but probably work in a somewhat similar manner. The exact amount requested
140 * may be tweaked if and when such conditions become publicly known.
141 */
142 return 65536;
143 }
144
145 bool trusted() const override {
146 // Avoid trusting a black box, don't count this as contributing entropy:
147 return false;
148 }
149
150 RandomNumberGenerator& rng() override { return m_hwrng; }
151
152 std::string name() const override { return m_hwrng.name(); }
153
154 private:
155 Processor_RNG m_hwrng;
156};
157
158#endif
159
160#if defined(BOTAN_HAS_JITTER_RNG)
161
162class Jitter_RNG_EntropySource final : public RNG_Based_EntropySource {
163 public:
164 explicit Jitter_RNG_EntropySource(Jitter_RNG::Mode mode) : m_jitter(mode) {}
165
166 std::string name() const override { return m_jitter.name(); }
167
168 RandomNumberGenerator& rng() override { return m_jitter; }
169
170 private:
171 Jitter_RNG m_jitter;
172};
173
174#endif
175
176} // namespace
177
179 m_sink(std::move(sink)), m_goal_bits(goal_bits) {
180 BOTAN_ARG_CHECK(m_sink != nullptr, "Entropy_Accumulator requires a sink");
181}
182
183void Entropy_Accumulator::add(std::span<const uint8_t> data, size_t estimated_entropy_bits) {
184 if(data.empty()) {
185 return;
186 }
187
188 m_sink(data);
189 m_bytes_contributed += data.size();
190 credit(estimated_entropy_bits, data.size());
191}
192
193void Entropy_Accumulator::credit(size_t estimated_entropy_bits, size_t data_bytes) {
194 // Never credit more entropy than the data could possibly contain
195 m_bits_collected += std::min(estimated_entropy_bits, 8 * data_bytes);
196}
197
199 Legacy_Poll_RNG rng(acc);
200 const size_t bytes_before = acc.bytes_contributed();
201 const size_t bits = this->poll(rng);
202 // Only the data provided during this poll can back the reported estimate
203 acc.credit(bits, acc.bytes_contributed() - bytes_before);
204}
205
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}
216
217std::unique_ptr<Entropy_Source> Entropy_Source::create(std::string_view name) {
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}
265
266void Entropy_Sources::add_source(std::unique_ptr<Entropy_Source> src) {
267 if(src) {
268 m_srcs.push_back(std::move(src));
269 }
270}
271
272std::vector<std::string> Entropy_Sources::enabled_sources() const {
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}
280
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}
294
295size_t Entropy_Sources::_gather_just(Entropy_Accumulator& acc, std::string_view the_src) {
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}
306
307size_t Entropy_Sources::poll(RandomNumberGenerator& rng, size_t poll_bits, std::chrono::milliseconds timeout) {
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}
330
331size_t Entropy_Sources::poll(RandomNumberGenerator& rng, size_t poll_bits) {
332 Entropy_Accumulator acc(poll_bits, additional_input_sink(rng));
333 return this->_gather(acc);
334}
335
336size_t Entropy_Sources::poll_just(RandomNumberGenerator& rng, std::string_view the_src) {
337 Entropy_Accumulator acc(RandomNumberGenerator::DefaultPollBits, additional_input_sink(rng));
338 return this->_gather_just(acc, the_src);
339}
340
341Entropy_Sources::Entropy_Sources(const std::vector<std::string>& sources) {
342 for(auto&& src_name : sources) {
344 }
345}
346
348 static Entropy_Sources global_entropy_sources({"rdseed", "hwrng", "getentropy", "system_rng", "system_stats"});
349
350 return global_entropy_sources;
351}
352
353} // namespace Botan
#define BOTAN_UNUSED
Definition assert.h:151
#define BOTAN_ARG_CHECK(expr, msg)
Definition assert.h:33
void add(std::span< const uint8_t > data, size_t estimated_entropy_bits)
Entropy_Accumulator(size_t goal_bits, Sink sink)
std::function< void(std::span< const uint8_t >)> Sink
Definition entropy_src.h:35
size_t bits_collected() const
Definition entropy_src.h:69
virtual void gather(Entropy_Accumulator &acc)
virtual std::string name() const =0
static std::unique_ptr< Entropy_Source > create(std::string_view type)
virtual size_t poll(RandomNumberGenerator &rng)
static Entropy_Sources & global_sources()
size_t _gather(Entropy_Accumulator &acc)
size_t poll_just(RandomNumberGenerator &rng, std::string_view src)
void add_source(std::unique_ptr< Entropy_Source > src)
size_t poll(RandomNumberGenerator &rng, size_t bits, std::chrono::milliseconds timeout)
size_t _gather_just(Entropy_Accumulator &acc, std::string_view src)
std::vector< std::string > enabled_sources() const
static bool available()
static constexpr size_t DefaultPollBits
Definition rng.h:50
const char * name
Definition ffi_tls.h:59
std::string fmt(std::string_view format, const T &... args)
Definition fmt.h:53
RandomNumberGenerator & system_rng()
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:128