Botan  2.8.0
Crypto and TLS for C++11
rng.h
Go to the documentation of this file.
1 /*
2 * Random Number Generator base classes
3 * (C) 1999-2009,2015,2016 Jack Lloyd
4 *
5 * Botan is released under the Simplified BSD License (see license.txt)
6 */
7 
8 #ifndef BOTAN_RANDOM_NUMBER_GENERATOR_H_
9 #define BOTAN_RANDOM_NUMBER_GENERATOR_H_
10 
11 #include <botan/secmem.h>
12 #include <botan/exceptn.h>
13 #include <botan/mutex.h>
14 #include <chrono>
15 #include <string>
16 
17 namespace Botan {
18 
19 class Entropy_Sources;
20 
21 /**
22 * An interface to a cryptographic random number generator
23 */
25  {
26  public:
27  virtual ~RandomNumberGenerator() = default;
28 
29  RandomNumberGenerator() = default;
30 
31  /*
32  * Never copy a RNG, create a new one
33  */
34  RandomNumberGenerator(const RandomNumberGenerator& rng) = delete;
35  RandomNumberGenerator& operator=(const RandomNumberGenerator& rng) = delete;
36 
37  /**
38  * Randomize a byte array.
39  * @param output the byte array to hold the random output.
40  * @param length the length of the byte array output in bytes.
41  */
42  virtual void randomize(uint8_t output[], size_t length) = 0;
43 
44  /**
45  * Returns false if it is known that this RNG object is not able to accept
46  * externally provided inputs (via add_entropy, randomize_with_input, etc).
47  * In this case, any such provided inputs are ignored.
48  *
49  * If this function returns true, then inputs may or may not be accepted.
50  */
51  virtual bool accepts_input() const = 0;
52 
53  /**
54  * Incorporate some additional data into the RNG state. For
55  * example adding nonces or timestamps from a peer's protocol
56  * message can help hedge against VM state rollback attacks.
57  * A few RNG types do not accept any externally provided input,
58  * in which case this function is a no-op.
59  *
60  * @param input a byte array containg the entropy to be added
61  * @param length the length of the byte array in
62  */
63  virtual void add_entropy(const uint8_t input[], size_t length) = 0;
64 
65  /**
66  * Incorporate some additional data into the RNG state.
67  */
68  template<typename T> void add_entropy_T(const T& t)
69  {
70  this->add_entropy(reinterpret_cast<const uint8_t*>(&t), sizeof(T));
71  }
72 
73  /**
74  * Incorporate entropy into the RNG state then produce output.
75  * Some RNG types implement this using a single operation, default
76  * calls add_entropy + randomize in sequence.
77  *
78  * Use this to further bind the outputs to your current
79  * process/protocol state. For instance if generating a new key
80  * for use in a session, include a session ID or other such
81  * value. See NIST SP 800-90 A, B, C series for more ideas.
82  *
83  * @param output buffer to hold the random output
84  * @param output_len size of the output buffer in bytes
85  * @param input entropy buffer to incorporate
86  * @param input_len size of the input buffer in bytes
87  */
88  virtual void randomize_with_input(uint8_t output[], size_t output_len,
89  const uint8_t input[], size_t input_len);
90 
91  /**
92  * This calls `randomize_with_input` using some timestamps as extra input.
93  *
94  * For a stateful RNG using non-random but potentially unique data the
95  * extra input can help protect against problems with fork, VM state
96  * rollback, or other cases where somehow an RNG state is duplicated. If
97  * both of the duplicated RNG states later incorporate a timestamp (and the
98  * timestamps don't themselves repeat), their outputs will diverge.
99  */
100  virtual void randomize_with_ts_input(uint8_t output[], size_t output_len);
101 
102  /**
103  * @return the name of this RNG type
104  */
105  virtual std::string name() const = 0;
106 
107  /**
108  * Clear all internally held values of this RNG
109  * @post is_seeded() == false
110  */
111  virtual void clear() = 0;
112 
113  /**
114  * Check whether this RNG is seeded.
115  * @return true if this RNG was already seeded, false otherwise.
116  */
117  virtual bool is_seeded() const = 0;
118 
119  /**
120  * Poll provided sources for up to poll_bits bits of entropy
121  * or until the timeout expires. Returns estimate of the number
122  * of bits collected.
123  */
124  virtual size_t reseed(Entropy_Sources& srcs,
125  size_t poll_bits = BOTAN_RNG_RESEED_POLL_BITS,
126  std::chrono::milliseconds poll_timeout = BOTAN_RNG_RESEED_DEFAULT_TIMEOUT);
127 
128  /**
129  * Reseed by reading specified bits from the RNG
130  */
131  virtual void reseed_from_rng(RandomNumberGenerator& rng,
132  size_t poll_bits = BOTAN_RNG_RESEED_POLL_BITS);
133 
134  // Some utility functions built on the interface above:
135 
136  /**
137  * Return a random vector
138  * @param bytes number of bytes in the result
139  * @return randomized vector of length bytes
140  */
142  {
143  secure_vector<uint8_t> output(bytes);
144  this->randomize(output.data(), output.size());
145  return output;
146  }
147 
148  /**
149  * Return a random byte
150  * @return random byte
151  */
152  uint8_t next_byte()
153  {
154  uint8_t b;
155  this->randomize(&b, 1);
156  return b;
157  }
158 
159  /**
160  * @return a random byte that is greater than zero
161  */
163  {
164  uint8_t b = this->next_byte();
165  while(b == 0)
166  b = this->next_byte();
167  return b;
168  }
169 
170  /**
171  * Create a seeded and active RNG object for general application use
172  * Added in 1.8.0
173  * Use AutoSeeded_RNG instead
174  */
175  BOTAN_DEPRECATED("Use AutoSeeded_RNG")
176  static RandomNumberGenerator* make_rng();
177  };
178 
179 /**
180 * Convenience typedef
181 */
183 
184 /**
185 * Hardware_RNG exists to tag hardware RNG types (PKCS11_RNG, TPM_RNG, RDRAND_RNG)
186 */
188  {
189  public:
190  virtual void clear() final override { /* no way to clear state of hardware RNG */ }
191  };
192 
193 /**
194 * Null/stub RNG - fails if you try to use it for anything
195 * This is not generally useful except for in certain tests
196 */
198  {
199  public:
200  bool is_seeded() const override { return false; }
201 
202  bool accepts_input() const override { return false; }
203 
204  void clear() override {}
205 
206  void randomize(uint8_t[], size_t) override
207  {
208  throw PRNG_Unseeded("Null_RNG called");
209  }
210 
211  void add_entropy(const uint8_t[], size_t) override {}
212 
213  std::string name() const override { return "Null_RNG"; }
214  };
215 
216 #if defined(BOTAN_TARGET_OS_HAS_THREADS)
217 /**
218 * Wraps access to a RNG in a mutex
219 * Note that most of the time it's much better to use a RNG per thread
220 * otherwise the RNG will act as an unnecessary contention point
221 */
222 class BOTAN_PUBLIC_API(2,0) Serialized_RNG final : public RandomNumberGenerator
223  {
224  public:
225  void randomize(uint8_t out[], size_t len) override
226  {
227  lock_guard_type<mutex_type> lock(m_mutex);
228  m_rng->randomize(out, len);
229  }
230 
231  bool accepts_input() const override
232  {
233  lock_guard_type<mutex_type> lock(m_mutex);
234  return m_rng->accepts_input();
235  }
236 
237  bool is_seeded() const override
238  {
239  lock_guard_type<mutex_type> lock(m_mutex);
240  return m_rng->is_seeded();
241  }
242 
243  void clear() override
244  {
245  lock_guard_type<mutex_type> lock(m_mutex);
246  m_rng->clear();
247  }
248 
249  std::string name() const override
250  {
251  lock_guard_type<mutex_type> lock(m_mutex);
252  return m_rng->name();
253  }
254 
255  size_t reseed(Entropy_Sources& src,
256  size_t poll_bits = BOTAN_RNG_RESEED_POLL_BITS,
257  std::chrono::milliseconds poll_timeout = BOTAN_RNG_RESEED_DEFAULT_TIMEOUT) override
258  {
259  lock_guard_type<mutex_type> lock(m_mutex);
260  return m_rng->reseed(src, poll_bits, poll_timeout);
261  }
262 
263  void add_entropy(const uint8_t in[], size_t len) override
264  {
265  lock_guard_type<mutex_type> lock(m_mutex);
266  m_rng->add_entropy(in, len);
267  }
268 
269  BOTAN_DEPRECATED("Use Serialized_RNG(new AutoSeeded_RNG)") Serialized_RNG();
270 
271  explicit Serialized_RNG(RandomNumberGenerator* rng) : m_rng(rng) {}
272  private:
273  mutable mutex_type m_mutex;
274  std::unique_ptr<RandomNumberGenerator> m_rng;
275  };
276 #endif
277 
278 }
279 
280 #endif
void add_entropy(const uint8_t[], size_t) override
Definition: rng.h:211
secure_vector< uint8_t > random_vec(size_t bytes)
Definition: rng.h:141
noop_mutex mutex_type
Definition: mutex.h:51
int(* final)(unsigned char *, CTX *)
#define BOTAN_PUBLIC_API(maj, min)
Definition: compiler.h:27
std::string name() const override
Definition: rng.h:213
void randomize(uint8_t[], size_t) override
Definition: rng.h:206
virtual void clear() final override
Definition: rng.h:190
std::string name
uint8_t next_nonzero_byte()
Definition: rng.h:162
void add_entropy_T(const T &t)
Definition: rng.h:68
bool is_seeded() const override
Definition: rng.h:200
Definition: alg_id.cpp:13
void clear() override
Definition: rng.h:204
fe T
Definition: ge.cpp:37
bool accepts_input() const override
Definition: rng.h:202
std::vector< T, secure_allocator< T > > secure_vector
Definition: secmem.h:88