Crypto++  5.6.3
Free C++ class library of cryptographic schemes
rdrand.h
Go to the documentation of this file.
1 // rdrand.h - written and placed in public domain by Jeffrey Walton and Uri Blumenthal.
2 // Copyright assigned to Crypto++ project.
3 
4 //! \file
5 //! \headerfile rdrand.h
6 //! \brief Classes for RDRAND and RDSEED
7 
8 #ifndef CRYPTOPP_RDRAND_H
9 #define CRYPTOPP_RDRAND_H
10 
11 #include "cryptlib.h"
12 
13 // This file (and friends) provides both RDRAND and RDSEED, but its somewhat
14 // experimental. They were added at Crypto++ 5.6.3. At compile time, it
15 // indirectly uses CRYPTOPP_BOOL_{X86|X32|X64} (via CRYPTOPP_CPUID_AVAILABLE)
16 // to select an implementation or "throw NotImplemented". At runtime, the
17 // class uses the result of CPUID to determine if RDRAND or RDSEED are
18 // available. A lazy throw strategy is used in case the CPU does not support
19 // the instruction. I.e., the throw is deferred until GenerateBlock() is called.
20 
21 // Microsoft added RDRAND in August 2012, VS2012. GCC added RDRAND in December 2010, GCC 4.6.
22 // Clang added RDRAND in July 2012, Clang 3.2. Intel added RDRAND in September 2011, ICC 12.1.
23 
24 NAMESPACE_BEGIN(CryptoPP)
25 
26 //! \brief Exception thrown when a RDRAND generator encounters
27 //! a generator related error.
28 class RDRAND_Err : public Exception
29 {
30 public:
31  RDRAND_Err(const std::string &operation)
32  : Exception(OTHER_ERROR, "RDRAND: " + operation + " operation failed") {}
33 };
34 
35 //! \brief Hardware generated random numbers using RDRAND instruction
36 //! \sa MaurerRandomnessTest() for random bit generators
38 {
39 public:
40  std::string AlgorithmName() const {return "RDRAND";}
41 
42  //! \brief Construct a RDRAND generator
43  //! \param retries the number of retries for failed calls to the hardware
44  //! \details RDRAND() constructs a generator with a maximum number of retires
45  //! for failed generation attempts.
46  RDRAND(unsigned int retries = 8) : m_retries(retries) {}
47 
48  virtual ~RDRAND() {}
49 
50  //! \brief Retrieve the number of retries used by the generator
51  //! \returns the number of times GenerateBlock() will attempt to recover from a failed generation
52  unsigned int GetRetries() const
53  {
54  return m_retries;
55  }
56 
57  //! \brief Set the number of retries used by the generator
58  //! \param retries number of times GenerateBlock() will attempt to recover from a failed generation
59  void SetRetries(unsigned int retries)
60  {
61  m_retries = retries;
62  }
63 
64  //! \brief Generate random array of bytes
65  //! \param output the byte buffer
66  //! \param size the length of the buffer, in bytes
67 #if (CRYPTOPP_BOOL_X86 || CRYPTOPP_BOOL_X32 || CRYPTOPP_BOOL_X64)
68  virtual void GenerateBlock(byte *output, size_t size);
69 #else
70  virtual void GenerateBlock(byte *output, size_t size) {
71  CRYPTOPP_UNUSED(output), CRYPTOPP_UNUSED(size);
72  throw NotImplemented("RDRAND: rdrand is not available on this platform");
73  }
74 #endif
75 
76  //! \brief Generate and discard n bytes
77  //! \param n the number of bytes to generate and discard
78  //! \details the RDSEED generator discards words, not bytes. If n is
79  //! not a multiple of a machine word, then it is rounded up to
80  //! that size.
81 #if (CRYPTOPP_BOOL_X86 || CRYPTOPP_BOOL_X32 || CRYPTOPP_BOOL_X64)
82  virtual void DiscardBytes(size_t n);
83 #else
84  virtual void DiscardBytes(size_t n) {
85  CRYPTOPP_UNUSED(n);
86  throw NotImplemented("RDRAND: rdrand is not available on this platform");
87  }
88 #endif
89 
90  //! Update RNG state with additional unpredictable values
91  //! \param input unused
92  //! \param length unused
93  //! \details The operation is a nop for this generator.
94  virtual void IncorporateEntropy(const byte *input, size_t length)
95  {
96  // Override to avoid the base class' throw.
97  CRYPTOPP_UNUSED(input); CRYPTOPP_UNUSED(length);
98  assert(0); // warn in debug builds
99  }
100 
101 private:
102  unsigned int m_retries;
103 };
104 
105 //! \brief Exception thrown when a RDSEED generator encounters
106 //! a generator related error.
107 class RDSEED_Err : public Exception
108 {
109 public:
110  RDSEED_Err(const std::string &operation)
111  : Exception(OTHER_ERROR, "RDSEED: " + operation + " operation failed") {}
112 };
113 
114 //! \brief Hardware generated random numbers using RDSEED instruction
115 //! \sa MaurerRandomnessTest() for random bit generators
117 {
118 public:
119  std::string AlgorithmName() const {return "RDSEED";}
120 
121  //! \brief Construct a RDSEED generator
122  //! \param retries the number of retries for failed calls to the hardware
123  //! \details RDSEED() constructs a generator with a maximum number of retires
124  //! for failed generation attempts.
125  RDSEED(unsigned int retries = 8) : m_retries(retries) {}
126 
127  virtual ~RDSEED() {}
128 
129  //! \brief Retrieve the number of retries used by the generator
130  //! \returns the number of times GenerateBlock() will attempt to recover from a failed generation
131  unsigned int GetRetries() const
132  {
133  return m_retries;
134  }
135 
136  //! \brief Set the number of retries used by the generator
137  //! \param retries number of times GenerateBlock() will attempt to recover from a failed generation
138  void SetRetries(unsigned int retries)
139  {
140  m_retries = retries;
141  }
142 
143  //! \brief Generate random array of bytes
144  //! \param output the byte buffer
145  //! \param size the length of the buffer, in bytes
146 #if (CRYPTOPP_BOOL_X86 || CRYPTOPP_BOOL_X32 || CRYPTOPP_BOOL_X64)
147  virtual void GenerateBlock(byte *output, size_t size);
148 #else
149  virtual void GenerateBlock(byte *output, size_t size) {
150  CRYPTOPP_UNUSED(output), CRYPTOPP_UNUSED(size);
151  throw NotImplemented("RDSEED: rdseed is not available on this platform");
152  }
153 #endif
154 
155  //! \brief Generate and discard n bytes
156  //! \param n the number of bytes to generate and discard
157  //! \details the RDSEED generator discards words, not bytes. If n is
158  //! not a multiple of a machine word, then it is rounded up to
159  //! that size.
160 #if (CRYPTOPP_BOOL_X86 || CRYPTOPP_BOOL_X32 || CRYPTOPP_BOOL_X64)
161  virtual void DiscardBytes(size_t n);
162 #else
163  virtual void DiscardBytes(size_t n) {
164  CRYPTOPP_UNUSED(n);
165  throw NotImplemented("RDSEED: rdseed is not available on this platform");
166  }
167 #endif
168 
169  //! Update RNG state with additional unpredictable values
170  //! \param input unused
171  //! \param length unused
172  //! \details The operation is a nop for this generator.
173  virtual void IncorporateEntropy(const byte *input, size_t length)
174  {
175  // Override to avoid the base class' throw.
176  CRYPTOPP_UNUSED(input); CRYPTOPP_UNUSED(length);
177  assert(0); // warn in debug builds
178  }
179 
180 private:
181  unsigned int m_retries;
182 };
183 
184 NAMESPACE_END
185 
186 #endif // CRYPTOPP_RDRAND_H
Base class for all exceptions thrown by Crypto++.
Definition: cryptlib.h:124
virtual void GenerateBlock(byte *output, size_t size)
Generate random array of bytes.
Definition: rdrand.h:149
virtual void GenerateBlock(byte *output, size_t size)
Generate random array of bytes.
Definition: rdrand.h:70
Hardware generated random numbers using RDRAND instruction.
Definition: rdrand.h:37
virtual void IncorporateEntropy(const byte *input, size_t length)
Update RNG state with additional unpredictable values.
Definition: rdrand.h:173
Abstract base classes that provide a uniform interface to this library.
Interface for random number generators.
Definition: cryptlib.h:1085
virtual void IncorporateEntropy(const byte *input, size_t length)
Update RNG state with additional unpredictable values.
Definition: rdrand.h:94
void SetRetries(unsigned int retries)
Set the number of retries used by the generator.
Definition: rdrand.h:138
Exception thrown when a RDRAND generator encounters a generator related error.
Definition: rdrand.h:28
virtual void DiscardBytes(size_t n)
Generate and discard n bytes.
Definition: rdrand.h:163
A method was called which was not implemented.
Definition: cryptlib.h:187
virtual void DiscardBytes(size_t n)
Generate and discard n bytes.
Definition: rdrand.h:84
unsigned int GetRetries() const
Retrieve the number of retries used by the generator.
Definition: rdrand.h:131
std::string AlgorithmName() const
Provides the name of this algorithm.
Definition: rdrand.h:40
Hardware generated random numbers using RDSEED instruction.
Definition: rdrand.h:116
RDSEED(unsigned int retries=8)
Construct a RDSEED generator.
Definition: rdrand.h:125
void SetRetries(unsigned int retries)
Set the number of retries used by the generator.
Definition: rdrand.h:59
Crypto++ library namespace.
RDRAND(unsigned int retries=8)
Construct a RDRAND generator.
Definition: rdrand.h:46
unsigned int GetRetries() const
Retrieve the number of retries used by the generator.
Definition: rdrand.h:52
std::string AlgorithmName() const
Provides the name of this algorithm.
Definition: rdrand.h:119
Exception thrown when a RDSEED generator encounters a generator related error.
Definition: rdrand.h:107