Botan 3.14.1
Crypto and TLS for C&
stateful_rng.h
Go to the documentation of this file.
1/*
2* (C) 2016 Jack Lloyd
3*
4* Botan is released under the Simplified BSD License (see license.txt)
5*/
6
7#ifndef BOTAN_STATEFUL_RNG_H_
8#define BOTAN_STATEFUL_RNG_H_
9
10#include <botan/mutex.h>
11#include <botan/rng.h>
12#include <memory>
13
14namespace Botan {
15
16namespace OS {
17class Fork_Detector;
18}
19
20/**
21* Inherited by RNGs which maintain in-process state, like HMAC_DRBG.
22* On Unix these RNGs are vulnerable to problems with fork, where the
23* RNG state is duplicated, and the parent and child process RNGs will
24* produce identical output until one of them reseeds. Stateful_RNG
25* reseeds itself whenever a fork is detected, or after a set number of
26* bytes have been output.
27*
28* Not implemented by RNGs which access an external RNG, such as the
29* system PRNG or a hardware RNG.
30*/
32 public:
33 /**
34 * Create a Stateful_RNG which reseeds from both an RNG and entropy sources
35 *
36 * @param rng is a reference to some RNG which will be used
37 * to perform the periodic reseeding
38 * @param entropy_sources will be polled to perform reseeding periodically
39 * @param reseed_interval specifies a limit of how many times
40 * the RNG will be called before automatic reseeding is performed
41 */
43
44 /**
45 * Create a Stateful_RNG which reseeds from another RNG
46 *
47 * @param rng is a reference to some RNG which will be used
48 * to perform the periodic reseeding
49 * @param reseed_interval specifies a limit of how many times
50 * the RNG will be called before automatic reseeding is performed
51 */
53
54 /**
55 * Create a Stateful_RNG which reseeds from entropy sources
56 *
57 * @param entropy_sources will be polled to perform reseeding periodically
58 * @param reseed_interval specifies a limit of how many times
59 * the RNG will be called before automatic reseeding is performed
60 */
61 Stateful_RNG(Entropy_Sources& entropy_sources, size_t reseed_interval);
62
63 /**
64 * In this case, automatic reseeding is impossible
65 */
67
68 ~Stateful_RNG() override;
69
70 Stateful_RNG(const Stateful_RNG& other) = delete;
71 Stateful_RNG(Stateful_RNG&& other) = delete;
72 Stateful_RNG& operator=(const Stateful_RNG& other) = delete;
74
75 /**
76 * Reset the RNG then consume this input as seed material
77 *
78 * The RNG is marked as seeded only if the input is at least
79 * security_level() bits long.
80 */
81 void initialize_with(std::span<const uint8_t> input);
82
83 /**
84 * Reset the RNG then consume this input as seed material
85 *
86 * The RNG is marked as seeded only if the input is at least
87 * security_level() bits long.
88 * @param input the seed material
89 * @param length the number of bytes in input
90 */
91 void initialize_with(const uint8_t input[], size_t length) { this->initialize_with(std::span(input, length)); }
92
93 /**
94 * Test whether this RNG has been seeded
95 * @return true if this RNG is seeded and ready for use
96 */
97 bool is_seeded() const final;
98
99 /**
100 * Test whether this RNG accepts externally provided input
101 * @return false if this RNG is known to ignore provided inputs
102 */
103 bool accepts_input() const final { return true; }
104
105 /**
106 * Mark state as requiring a reseed on next use
107 */
108 void force_reseed();
109
110 /**
111 * Reseed this RNG from another RNG
112 * @param rng the RNG to draw seed material from
113 * @param poll_bits the number of bits to collect
114 */
115 void reseed_from_rng(RandomNumberGenerator& rng, size_t poll_bits = RandomNumberGenerator::DefaultPollBits) final;
116
117 /**
118 * Poll provided sources for up to poll_bits bits of entropy.
119 * Returns estimate of the number of bits collected.
120 */
121 size_t reseed_from_sources(Entropy_Sources& srcs,
122 size_t poll_bits = RandomNumberGenerator::DefaultPollBits) final;
123
124 /**
125 * Return the security level of this DRBG
126 * @return intended security level of this DRBG
127 */
128 virtual size_t security_level() const = 0;
129
130 /**
131 * Return the largest number of bytes this DRBG will produce per request
132 * Some DRBGs have a notion of the maximum number of bytes per
133 * request. Longer requests (to randomize) will be treated as
134 * multiple requests, and may initiate reseeding multiple times,
135 * depending on the values of max_number_of_bytes_per_request and
136 * reseed_interval(). This function returns zero if the RNG in
137 * question does not have such a notion.
138 *
139 * @return max number of bytes per request (or zero)
140 */
141 virtual size_t max_number_of_bytes_per_request() const = 0;
142
143 /**
144 * Return how many requests may be made before automatic reseeding
145 * @return the reseed interval, or zero if automatic reseeding is disabled
146 */
147 size_t reseed_interval() const { return m_reseed_interval; }
148
149 /**
150 * Clear all internally held values of this RNG
151 */
152 void clear() final;
153
154 protected:
155 /**
156 * Reseed if the reseed interval has elapsed, or throw if unseeded
157 */
158 void reseed_check();
159
160 /**
161 * Generate output, incorporating the provided input
162 * @param output the buffer to fill
163 * @param input additional input to incorporate
164 */
165 virtual void generate_output(std::span<uint8_t> output, std::span<const uint8_t> input) = 0;
166
167 /**
168 * Incorporate the provided input into the RNG state
169 * @param input the seed material
170 */
171 virtual void update(std::span<const uint8_t> input) = 0;
172
173 /**
174 * Clear the subclass specific portion of the RNG state
175 */
176 virtual void clear_state() = 0;
177
178 private:
179 void generate_batched_output(std::span<uint8_t> output, std::span<const uint8_t> input);
180
181 void fill_bytes_with_input(std::span<uint8_t> output, std::span<const uint8_t> input) final;
182
183 void accept_seed_material(std::span<const uint8_t> input) final;
184
185 size_t finish_reseed(size_t bits_collected);
186
187 void reset_reseed_counter();
188
189 bool fork_detected() const;
190
191 mutable recursive_mutex_type m_mutex;
192
193 // A non-owned and possibly null pointer to shared RNG
194 RandomNumberGenerator* m_underlying_rng = nullptr;
195
196 // A non-owned and possibly null pointer to a shared Entropy_Source
197 Entropy_Sources* m_entropy_sources = nullptr;
198
199 const size_t m_reseed_interval;
200
201 // Never null; rebaselined by clear() and by each successful seeding
202 std::unique_ptr<OS::Fork_Detector> m_fork_detector;
203
204 /*
205 * Set to 1 after a successful seeding, then incremented. Reset
206 * to 0 by clear() or a fork. This logic is used even if
207 * automatic reseeding is disabled (via m_reseed_interval = 0)
208 */
209 size_t m_reseed_counter = 0;
210};
211
212} // namespace Botan
213
214#endif
#define BOTAN_PUBLIC_API(maj, min)
Definition api.h:21
static constexpr size_t DefaultPollBits
Definition rng.h:50
Stateful_RNG & operator=(const Stateful_RNG &other)=delete
size_t reseed_interval() const
Stateful_RNG(Stateful_RNG &&other)=delete
Stateful_RNG(const Stateful_RNG &other)=delete
virtual size_t security_level() const =0
virtual void clear_state()=0
~Stateful_RNG() override
Stateful_RNG(RandomNumberGenerator &rng, Entropy_Sources &entropy_sources, size_t reseed_interval)
void initialize_with(const uint8_t input[], size_t length)
virtual void generate_output(std::span< uint8_t > output, std::span< const uint8_t > input)=0
bool accepts_input() const final
virtual size_t max_number_of_bytes_per_request() const =0
virtual void update(std::span< const uint8_t > input)=0
void initialize_with(std::span< const uint8_t > input)
Stateful_RNG & operator=(Stateful_RNG &&other)=delete
noop_mutex recursive_mutex_type
Definition mutex.h:41