Botan 3.14.1
Crypto and TLS for C&
entropy_src.h
Go to the documentation of this file.
1/*
2* EntropySource
3* (C) 2008,2009,2014,2015,2016 Jack Lloyd
4*
5* Botan is released under the Simplified BSD License (see license.txt)
6*/
7
8#ifndef BOTAN_ENTROPY_H_
9#define BOTAN_ENTROPY_H_
10
11#include <botan/api.h>
12#include <chrono>
13#include <functional>
14#include <memory>
15#include <span>
16#include <string>
17#include <string_view>
18#include <type_traits>
19#include <vector>
20
21namespace Botan {
22
24
25/**
26* Collects entropy on behalf of an RNG which is being seeded
27*
28* An Entropy_Source is handed an accumulator rather than the RNG itself. A
29* source can only contribute data plus a conservative estimate of how much
30* entropy that data contains. The RNG later decides, from the accumulated
31* estimate, whether the seeding succeeded.
32*/
34 public:
35 using Sink = std::function<void(std::span<const uint8_t>)>;
36
37 /**
38 * @param goal_bits how many bits of entropy the caller hopes to collect
39 * @param sink receives all data contributed to the accumulator
40 */
42
48
49 /**
50 * Contribute data along with a conservative estimate of the entropy it
51 * contains. Data of unknown or untrusted quality should be contributed
52 * with an estimate of zero; it is still mixed into the RNG but not
53 * credited. The estimate is capped at the bit length of the data.
54 */
55 void add(std::span<const uint8_t> data, size_t estimated_entropy_bits);
56
57 /**
58 * Contribute the representation of a trivial object, see add
59 */
60 template <typename T>
61 requires std::is_standard_layout_v<T> && std::is_trivial_v<T>
62 void add_T(const T& t, size_t estimated_entropy_bits) {
63 this->add(std::span(reinterpret_cast<const uint8_t*>(&t), sizeof(T)), estimated_entropy_bits);
64 }
65
66 /**
67 * @return the entropy estimate accumulated so far, in bits
68 */
69 size_t bits_collected() const { return m_bits_collected; }
70
71 /**
72 * @return the number of bits the caller hopes to collect
73 */
74 size_t goal_bits() const { return m_goal_bits; }
75
76 /**
77 * @return true once the goal has been reached; a source may stop polling early
78 */
79 bool goal_reached() const { return m_bits_collected >= m_goal_bits; }
80
81 private:
82 friend class Entropy_Source;
83
84 size_t bytes_contributed() const { return m_bytes_contributed; }
85
86 /*
87 * Credit entropy for data already contributed, capped at the bit length
88 * of @p data_bytes. Used only to support the legacy Entropy_Source::poll
89 * interface, which reports its estimate after the fact.
90 */
91 void credit(size_t estimated_entropy_bits, size_t data_bytes);
92
93 Sink m_sink;
94 size_t m_goal_bits;
95 size_t m_bytes_contributed = 0;
96 size_t m_bits_collected = 0;
97};
98
99/**
100* Abstract interface to a source of entropy
101*/
103 public:
104 /**
105 * Return a new entropy source of a particular type, or null
106 * Each entropy source may require substantial resources (eg, a file handle
107 * or socket instance), so try to share them among multiple RNGs, or just
108 * use the preconfigured global list accessed by Entropy_Sources::global_sources()
109 */
110 static std::unique_ptr<Entropy_Source> create(std::string_view type);
111
112 /**
113 * Return a free-form string identifying this entropy source
114 */
115 virtual std::string name() const = 0;
116
117 /**
118 * Perform an entropy gathering poll
119 *
120 * Contribute data to @p acc, each contribution along with a conservative
121 * estimate of the entropy it contains. Data which should be mixed in but
122 * not trusted is contributed with an estimate of zero. A source may stop
123 * early once acc.goal_reached() returns true.
124 *
125 * Any implementation of this function should be thread safe; it may be
126 * called concurrently in multiple threads if multiple stateful RNGs reseed
127 * across different threads.
128 *
129 * The default implementation exists only to support subclasses which
130 * implement the legacy poll interface, and forwards to poll.
131 *
132 * Note that applications should not directly invoke this function to
133 * perform reseeding; use `RandomNumberGenerator::reseed_from` with an
134 * instance of `Entropy_Sources` which contains this source.
135 *
136 * TODO(Botan4) make this a pure virtual
137 */
138 virtual void gather(Entropy_Accumulator& acc);
139
140 /**
141 * Perform an entropy gathering poll (legacy interface)
142 * @param rng will be provided with entropy via calls to add_entropy
143 * @return conservative estimate of actual entropy added to rng during poll
144 *
145 * New sources should implement gather instead. The default implementation
146 * of this function forwards to gather.
147 *
148 * TODO(Botan4) remove this function
149 */
150 virtual size_t poll(RandomNumberGenerator& rng);
151
152 /**
153 * Default constructor
154 */
155 Entropy_Source() = default;
156 Entropy_Source(const Entropy_Source& other) = delete;
158 Entropy_Source& operator=(const Entropy_Source& other) = delete;
160
161 virtual ~Entropy_Source() = default;
162};
163
164/**
165* A collection of entropy sources which can be polled together
166*/
168 public:
169 /**
170 * Access the process-wide set of entropy sources used by default
171 * @warning This object is not synchronized. For general usage (eg polling)
172 * this is fine. However if you use global_sources().add_source() concurrently
173 * with a poll, likely a race leading to memory corruption will occur; only
174 * add a new entropy source at the start of main before RNG objects are created.
175 */
177
178 /**
179 * Add an entropy source to this collection
180 * @param src the source to add
181 */
182 void add_source(std::unique_ptr<Entropy_Source> src);
183
184 /**
185 * List the entropy sources in this collection
186 * @return the names of the enabled sources
187 */
188 std::vector<std::string> enabled_sources() const;
189
190 /**
191 * Poll all sources to collect @p bits of entropy with a @p timeout.
192 * Entropy collection is aborted as soon as either the requested number of
193 * bits are obtained or the timeout runs out. If the target system does not
194 * provide a clock, the timeout is ignored.
195 *
196 * Note that the timeout is cooperative. If the poll() method of an entropy
197 * source blocks forever, this invocation will potentially also block.
198 *
199 * @returns the number of bits collected from the entropy sources
200 *
201 * TODO(Botan4) remove this variant, and the <chrono> include above
202 */
203 BOTAN_DEPRECATED("Use version without a timeout argument")
204 size_t poll(RandomNumberGenerator& rng, size_t bits, std::chrono::milliseconds timeout);
205
206 /**
207 * Poll all sources into @p acc until its goal is reached
208 *
209 * This should not be called by applications and is not covered by SemVer
210 *
211 * @returns the number of bits collected during this call
212 */
213 size_t _gather(Entropy_Accumulator& acc);
214
215 /**
216 * Poll just a single named source into @p acc. Ordinally only used for testing
217 *
218 * This should not be called by applications and is not covered by SemVer
219 *
220 * @returns the number of bits collected during this call, or zero if no
221 * source with this name exists
222 */
223 size_t _gather_just(Entropy_Accumulator& acc, std::string_view src);
224
225 /**
226 * Poll all sources to collect @p bits of entropy. Entropy collection is
227 * aborted as soon as the requested number of bits are obtained.
228 *
229 * The data is mixed into @p rng without affecting its seeded state. To
230 * seed an RNG from entropy sources use RandomNumberGenerator::reseed_from
231 *
232 * @returns the number of bits collected from the entropy sources
233 */
234 size_t poll(RandomNumberGenerator& rng, size_t bits);
235
236 /**
237 * Poll just a single named source. Ordinally only used for testing
238 *
239 * The data is mixed into @p rng without affecting its seeded state.
240 */
241 size_t poll_just(RandomNumberGenerator& rng, std::string_view src);
242
243 /**
244 * Create an empty collection of entropy sources
245 */
246 Entropy_Sources() = default;
247
248 /**
249 * Create a collection containing the named entropy sources
250 * @param sources the names of the sources to enable
251 */
252 explicit Entropy_Sources(const std::vector<std::string>& sources);
253
254 Entropy_Sources(const Entropy_Sources& other) = delete;
258 ~Entropy_Sources() = default;
259
260 private:
261 std::vector<std::unique_ptr<Entropy_Source>> m_srcs;
262};
263
264} // namespace Botan
265
266#endif
#define BOTAN_PUBLIC_API(maj, min)
Definition api.h:21
#define BOTAN_DEPRECATED(msg)
Definition api.h:73
void add(std::span< const uint8_t > data, size_t estimated_entropy_bits)
Entropy_Accumulator(Entropy_Accumulator &&other)=delete
Entropy_Accumulator(const Entropy_Accumulator &other)=delete
Entropy_Accumulator & operator=(Entropy_Accumulator &&other)=delete
Entropy_Accumulator & operator=(const Entropy_Accumulator &other)=delete
Entropy_Accumulator(size_t goal_bits, Sink sink)
void add_T(const T &t, size_t estimated_entropy_bits)
Definition entropy_src.h:62
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)
Entropy_Source(const Entropy_Source &other)=delete
Entropy_Source(Entropy_Source &&other)=delete
virtual ~Entropy_Source()=default
Entropy_Source & operator=(Entropy_Source &&other)=delete
Entropy_Source & operator=(const Entropy_Source &other)=delete
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)
Entropy_Sources(Entropy_Sources &&other)=delete
Entropy_Sources & operator=(Entropy_Sources &&other)=delete
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)
Entropy_Sources(const Entropy_Sources &other)=delete
Entropy_Sources & operator=(const Entropy_Sources &other)=delete
std::vector< std::string > enabled_sources() const