Botan  1.10.9
rng.h
Go to the documentation of this file.
1 /*
2 * RandomNumberGenerator
3 * (C) 1999-2009 Jack Lloyd
4 *
5 * Distributed under the terms of the Botan license
6 */
7 
8 #ifndef BOTAN_RANDOM_NUMBER_GENERATOR_H__
9 #define BOTAN_RANDOM_NUMBER_GENERATOR_H__
10 
11 #include <botan/entropy_src.h>
12 #include <botan/exceptn.h>
13 #include <string>
14 
15 namespace Botan {
16 
17 /**
18 * This class represents a random number (RNG) generator object.
19 */
20 class BOTAN_DLL RandomNumberGenerator
21  {
22  public:
23  /**
24  * Create a seeded and active RNG object for general application use
25  */
26  static RandomNumberGenerator* make_rng();
27 
28  /**
29  * Randomize a byte array.
30  * @param output the byte array to hold the random output.
31  * @param length the length of the byte array output.
32  */
33  virtual void randomize(byte output[], size_t length) = 0;
34 
35  /**
36  * Return a random vector
37  * @param bytes number of bytes in the result
38  * @return randomized vector of length bytes
39  */
41  {
42  SecureVector<byte> output(bytes);
43  randomize(&output[0], output.size());
44  return output;
45  }
46 
47  /**
48  * Return a random byte
49  * @return random byte
50  */
51  byte next_byte();
52 
53  /**
54  * Check whether this RNG is seeded.
55  * @return true if this RNG was already seeded, false otherwise.
56  */
57  virtual bool is_seeded() const { return true; }
58 
59  /**
60  * Clear all internally held values of this RNG.
61  */
62  virtual void clear() = 0;
63 
64  /**
65  * Return the name of this object
66  */
67  virtual std::string name() const = 0;
68 
69  /**
70  * Seed this RNG using the entropy sources it contains.
71  * @param bits_to_collect is the number of bits of entropy to
72  attempt to gather from the entropy sources
73  */
74  virtual void reseed(size_t bits_to_collect) = 0;
75 
76  /**
77  * Add this entropy source to the RNG object
78  * @param source the entropy source which will be retained and used by RNG
79  */
80  virtual void add_entropy_source(EntropySource* source) = 0;
81 
82  /**
83  * Add entropy to this RNG.
84  * @param in a byte array containg the entropy to be added
85  * @param length the length of the byte array in
86  */
87  virtual void add_entropy(const byte in[], size_t length) = 0;
88 
91  private:
93  RandomNumberGenerator& operator=(const RandomNumberGenerator&)
94  { return (*this); }
95  };
96 
97 /**
98 * Null/stub RNG - fails if you try to use it for anything
99 */
100 class BOTAN_DLL Null_RNG : public RandomNumberGenerator
101  {
102  public:
103  void randomize(byte[], size_t) { throw PRNG_Unseeded("Null_RNG"); }
104  void clear() {}
105  std::string name() const { return "Null_RNG"; }
106 
107  void reseed(size_t) {}
108  bool is_seeded() const { return false; }
109  void add_entropy(const byte[], size_t) {}
110  void add_entropy_source(EntropySource* es) { delete es; }
111  };
112 
113 }
114 
115 #endif
void reseed(size_t)
Definition: rng.h:107
std::string name() const
Definition: rng.h:105
virtual bool is_seeded() const
Definition: rng.h:57
SecureVector< byte > random_vec(size_t bytes)
Definition: rng.h:40
void add_entropy(const byte[], size_t)
Definition: rng.h:109
unsigned char byte
Definition: types.h:22
void clear()
Definition: rng.h:104
size_t size() const
Definition: secmem.h:29
bool is_seeded() const
Definition: rng.h:108
virtual ~RandomNumberGenerator()
Definition: rng.h:90
void randomize(byte[], size_t)
Definition: rng.h:103
void add_entropy_source(EntropySource *es)
Definition: rng.h:110