Crypto++  5.6.3
Free C++ class library of cryptographic schemes
osrng.h
Go to the documentation of this file.
1 // osrng.h - written and placed in the public domain by Wei Dai
2 
3 //! \file
4 //! \headerfile osrng.h
5 //! \brief Classes for access to the operating system's random number generators
6 
7 #ifndef CRYPTOPP_OSRNG_H
8 #define CRYPTOPP_OSRNG_H
9 
10 #include "config.h"
11 
12 #ifdef OS_RNG_AVAILABLE
13 
14 #include "cryptlib.h"
15 #include "randpool.h"
16 #include "smartptr.h"
17 #include "fips140.h"
18 #include "rng.h"
19 #include "aes.h"
20 #include "sha.h"
21 
22 NAMESPACE_BEGIN(CryptoPP)
23 
24 //! \class OS_RNG_Err
25 //! \brief Exception thrown when an operating system error is encountered
26 class CRYPTOPP_DLL OS_RNG_Err : public Exception
27 {
28 public:
29  //! \brief Constructs an OS_RNG_Err
30  //! \param operation the operation or API call when the error occurs
31  OS_RNG_Err(const std::string &operation);
32 };
33 
34 #ifdef NONBLOCKING_RNG_AVAILABLE
35 
36 #ifdef CRYPTOPP_WIN32_AVAILABLE
37 //! \class MicrosoftCryptoProvider
38 //! \brief Wrapper for Microsoft crypto service provider
39 //! \sa \def USE_MS_CRYPTOAPI, \def WORKAROUND_MS_BUG_Q258000
40 class CRYPTOPP_DLL MicrosoftCryptoProvider
41 {
42 public:
43  //! \brief Construct a MicrosoftCryptoProvider
46 
47 // type HCRYPTPROV, avoid #include <windows.h>
48 #if defined(__CYGWIN__) && defined(__x86_64__)
49  typedef unsigned long long ProviderHandle;
50 #elif defined(WIN64) || defined(_WIN64)
51  typedef unsigned __int64 ProviderHandle;
52 #else
53  typedef unsigned long ProviderHandle;
54 #endif
55 
56  //! \brief Retrieves the CryptoAPI provider handle
57  //! \returns CryptoAPI provider handle
58  //! \details The handle is acquired by a call to CryptAcquireContext().
59  //! CryptReleaseContext() is called upon destruction.
60  ProviderHandle GetProviderHandle() const {return m_hProvider;}
61 
62 private:
63  ProviderHandle m_hProvider;
64 };
65 
66 #if defined(_MSC_VER)
67 # pragma comment(lib, "advapi32.lib")
68 #endif
69 
70 #endif //CRYPTOPP_WIN32_AVAILABLE
71 
72 //! \class NonblockingRng
73 //! \brief Wrapper class for /dev/random and /dev/srandom
74 //! \details Encapsulates CryptoAPI's CryptGenRandom() on Windows, or /dev/urandom on Unix and compatibles.
75 class CRYPTOPP_DLL NonblockingRng : public RandomNumberGenerator
76 {
77 public:
78  //! \brief Construct a NonblockingRng
80  ~NonblockingRng();
81 
82  //! \brief Generate random array of bytes
83  //! \param output the byte buffer
84  //! \param size the length of the buffer, in bytes
85  //! \details GenerateIntoBufferedTransformation() calls are routed to GenerateBlock().
86  void GenerateBlock(byte *output, size_t size);
87 
88 protected:
89 #ifdef CRYPTOPP_WIN32_AVAILABLE
90 # ifndef WORKAROUND_MS_BUG_Q258000
91  MicrosoftCryptoProvider m_Provider;
92 # endif
93 #else
94  int m_fd;
95 #endif
96 };
97 
98 #endif
99 
100 #if defined(BLOCKING_RNG_AVAILABLE) || defined(CRYPTOPP_DOXYGEN_PROCESSING)
101 
102 //! \class BlockingRng
103 //! \brief Wrapper class for /dev/random and /dev/srandom
104 //! \details Encapsulates /dev/random on Linux, OS X and Unix; and /dev/srandom on the BSDs.
105 class CRYPTOPP_DLL BlockingRng : public RandomNumberGenerator
106 {
107 public:
108  //! \brief Construct a BlockingRng
109  BlockingRng();
110  ~BlockingRng();
111 
112  //! \brief Generate random array of bytes
113  //! \param output the byte buffer
114  //! \param size the length of the buffer, in bytes
115  //! \details GenerateIntoBufferedTransformation() calls are routed to GenerateBlock().
116  void GenerateBlock(byte *output, size_t size);
117 
118 protected:
119  int m_fd;
120 };
121 
122 #endif
123 
124 //! OS_GenerateRandomBlock
125 //! \brief Generate random array of bytes
126 //! \param blocking specifies whther a bobcking or non-blocking generator should be used
127 //! \param output the byte buffer
128 //! \param size the length of the buffer, in bytes
129 //! \details OS_GenerateRandomBlock() uses the underlying operating system's
130 //! random number generator. On Windows, CryptGenRandom() is called using NonblockingRng.
131 //! \details On Unix and compatibles, /dev/urandom is called if blocking is false using
132 //! NonblockingRng. If blocking is true, then either /dev/randomd or /dev/srandom is used
133 //! by way of BlockingRng, if available.
134 CRYPTOPP_DLL void CRYPTOPP_API OS_GenerateRandomBlock(bool blocking, byte *output, size_t size);
135 
136 
137 //! \class AutoSeededRandomPool
138 //! \brief Automatically Seeded Randomness Pool
139 //! \details This class seeds itself using an operating system provided RNG.
140 class CRYPTOPP_DLL AutoSeededRandomPool : public RandomPool
141 {
142 public:
143  //! \brief Construct an AutoSeededRandomPool
144  //! \param blocking controls seeding with BlockingRng or NonblockingRng
145  //! \param seedSize the size of the seed, in bytes
146  //! \details Use blocking to choose seeding with BlockingRng or NonblockingRng.
147  //! The parameter is ignored if only one of these is available.
148  explicit AutoSeededRandomPool(bool blocking = false, unsigned int seedSize = 32)
149  {Reseed(blocking, seedSize);}
150 
151  //! \brief Reseed an AutoSeededRandomPool
152  //! \param blocking controls seeding with BlockingRng or NonblockingRng
153  //! \param seedSize the size of the seed, in bytes
154  void Reseed(bool blocking = false, unsigned int seedSize = 32);
155 };
156 
157 //! \class AutoSeededX917RNG
158 //! \tparam BLOCK_CIPHER a block cipher
159 //! \brief Automatically Seeded X9.17 RNG
160 //! \details AutoSeededX917RNG is from ANSI X9.17 Appendix C, seeded using an OS provided RNG.
161 //! If 3-key TripleDES (DES_EDE3) is used, then its a X9.17 conforming generator. If AES is
162 //! used, then its a X9.31 conforming generator.
163 //! \details Though ANSI X9 prescribes 3-key TripleDES, the template parameter BLOCK_CIPHER can be any
164 //! BlockTransformation derived class.
165 //! \sa X917RNG, DefaultAutoSeededRNG
166 template <class BLOCK_CIPHER>
168 {
169 public:
170  //! \brief Construct an AutoSeededX917RNG
171  //! \param blocking controls seeding with BlockingRng or NonblockingRng
172  //! \param autoSeed controls auto seeding of the generator
173  //! \details Use blocking to choose seeding with BlockingRng or NonblockingRng.
174  //! The parameter is ignored if only one of these is available.
175  //! \sa X917RNG
176  explicit AutoSeededX917RNG(bool blocking = false, bool autoSeed = true)
177  {if (autoSeed) Reseed(blocking);}
178 
179  //! \brief Reseed an AutoSeededX917RNG
180  //! \param blocking controls seeding with BlockingRng or NonblockingRng
181  //! \param additionalEntropy additional entropy to add to the generator
182  //! \param length the size of the additional entropy, in bytes
183  //! \details Internally, the generator uses SHA256 to extract the entropy from
184  //! from the seed and then stretch the material for the block cipher's key
185  //! and initialization vector.
186  void Reseed(bool blocking = false, const byte *additionalEntropy = NULL, size_t length = 0);
187 
188  //! \brief Deterministically reseed an AutoSeededX917RNG for testing
189  //! \param key the key to use for the deterministic reseeding
190  //! \param keylength the size of the key, in bytes
191  //! \param seed the seed to use for the deterministic reseeding
192  //! \param timeVector a time vector to use for deterministic reseeding
193  //! \details This is a testing interface for testing purposes, and should \a NOT
194  //! be used in production.
195  void Reseed(const byte *key, size_t keylength, const byte *seed, const byte *timeVector);
196 
197  bool CanIncorporateEntropy() const {return true;}
198  void IncorporateEntropy(const byte *input, size_t length) {Reseed(false, input, length);}
199  void GenerateIntoBufferedTransformation(BufferedTransformation &target, const std::string &channel, lword length)
200  {m_rng->GenerateIntoBufferedTransformation(target, channel, length);}
201 
202 private:
204 };
205 
206 template <class BLOCK_CIPHER>
207 void AutoSeededX917RNG<BLOCK_CIPHER>::Reseed(const byte *key, size_t keylength, const byte *seed, const byte *timeVector)
208 {
209  m_rng.reset(new X917RNG(new typename BLOCK_CIPHER::Encryption(key, keylength), seed, timeVector));
210 }
211 
212 template <class BLOCK_CIPHER>
213 void AutoSeededX917RNG<BLOCK_CIPHER>::Reseed(bool blocking, const byte *input, size_t length)
214 {
215  SecByteBlock seed(BLOCK_CIPHER::BLOCKSIZE + BLOCK_CIPHER::DEFAULT_KEYLENGTH);
216  const byte *key;
217  do
218  {
219  OS_GenerateRandomBlock(blocking, seed, seed.size());
220  if (length > 0)
221  {
222  SHA256 hash;
223  hash.Update(seed, seed.size());
224  hash.Update(input, length);
225  hash.TruncatedFinal(seed, UnsignedMin(hash.DigestSize(), seed.size()));
226  }
227  key = seed + BLOCK_CIPHER::BLOCKSIZE;
228  } // check that seed and key don't have same value
229  while (memcmp(key, seed, STDMIN((unsigned int)BLOCK_CIPHER::BLOCKSIZE, (unsigned int)BLOCK_CIPHER::DEFAULT_KEYLENGTH)) == 0);
230 
231  Reseed(key, BLOCK_CIPHER::DEFAULT_KEYLENGTH, seed, NULL);
232 }
233 
234 CRYPTOPP_DLL_TEMPLATE_CLASS AutoSeededX917RNG<AES>;
235 
236 #if defined(CRYPTOPP_DOXYGEN_PROCESSING)
237 //! \class DefaultAutoSeededRNG
238 //! \brief A typedef providing a default generator
239 //! \details DefaultAutoSeededRNG is a typedef of either AutoSeededX917RNG<AES> or AutoSeededRandomPool.
240 //! If CRYPTOPP_ENABLE_COMPLIANCE_WITH_FIPS_140_2 is defined, then DefaultAutoSeededRNG is
241 //! AutoSeededX917RNG<AES>. Otherwise, DefaultAutoSeededRNG is AutoSeededRandomPool.
243 #else
244 // AutoSeededX917RNG<AES> in FIPS mode, otherwise it's AutoSeededRandomPool
245 #if CRYPTOPP_ENABLE_COMPLIANCE_WITH_FIPS_140_2
247 #else
249 #endif
250 #endif // CRYPTOPP_DOXYGEN_PROCESSING
251 
252 NAMESPACE_END
253 
254 #endif
255 
256 #endif
Base class for all exceptions thrown by the library.
Definition: cryptlib.h:139
AutoSeededRandomPool(bool blocking=false, unsigned int seedSize=32)
Construct an AutoSeededRandomPool.
Definition: osrng.h:148
Wrapper for Microsoft crypto service provider.
Definition: osrng.h:40
Randomness Pool.
Definition: randpool.h:25
implements the SHA-256 standard
Definition: sha.h:32
Wrapper class for /dev/random and /dev/srandom.
Definition: osrng.h:75
Class file for Randomness Pool.
void Reseed(bool blocking=false, const byte *additionalEntropy=NULL, size_t length=0)
Reseed an AutoSeededX917RNG.
Definition: osrng.h:213
virtual void GenerateBlock(byte *output, size_t size)
Generate random array of bytes.
Definition: cryptlib.cpp:329
ANSI X9.17 RNG.
Definition: rng.h:48
Abstract base classes that provide a uniform interface to this library.
unsigned int DigestSize() const
Provides the digest size of the hash.
Definition: iterhash.h:85
size_type size() const
Provides the count of elements in the SecBlock.
Definition: secblock.h:523
Classes for automatic resource management.
Library configuration file.
Interface for random number generators.
Definition: cryptlib.h:1186
SecBlock typedef.
Definition: secblock.h:730
Interface for buffered transformations.
Definition: cryptlib.h:1352
void GenerateIntoBufferedTransformation(BufferedTransformation &target, const std::string &channel, lword length)
Generate random bytes into a BufferedTransformation.
Definition: osrng.h:199
Exception thrown when an operating system error is encountered.
Definition: osrng.h:26
Automatically Seeded Randomness Pool.
Definition: osrng.h:140
Class file for the AES cipher (Rijndael)
const T1 UnsignedMin(const T1 &a, const T2 &b)
Safe comparison of values that could be neagtive and incorrectly promoted.
Definition: misc.h:433
Miscellaneous classes for RNGs.
Automatically Seeded X9.17 RNG.
Definition: osrng.h:167
const T & STDMIN(const T &a, const T &b)
Replacement function for std::min.
Definition: misc.h:397
Classes for SHA-1 and SHA-2 family of message digests.
Wrapper class for /dev/random and /dev/srandom.
Definition: osrng.h:105
Classes and functions for the FIPS 140-2 validated library.
bool CanIncorporateEntropy() const
Determines if a generator can accept additional entropy.
Definition: osrng.h:197
void OS_GenerateRandomBlock(bool blocking, byte *output, size_t size)
OS_GenerateRandomBlock.
Definition: osrng.cpp:158
AutoSeededX917RNG(bool blocking=false, bool autoSeed=true)
Construct an AutoSeededX917RNG.
Definition: osrng.h:176
ProviderHandle GetProviderHandle() const
Retrieves the CryptoAPI provider handle.
Definition: osrng.h:60
Crypto++ library namespace.
Ensures an object is not copyable.
Definition: misc.h:189
virtual void GenerateIntoBufferedTransformation(BufferedTransformation &target, const std::string &channel, lword length)
Generate random bytes into a BufferedTransformation.
Definition: cryptlib.cpp:347
void IncorporateEntropy(const byte *input, size_t length)
Update RNG state with additional unpredictable values.
Definition: osrng.h:198
A typedef providing a default generator.
Definition: osrng.h:242