Crypto++  8.6
Free C++ class library of cryptographic schemes
padlkrng.h
Go to the documentation of this file.
1 // via-rng.h - written and placed in public domain by Jeffrey Walton
2 
3 /// \file padlkrng.h
4 /// \brief Classes for VIA Padlock RNG
5 /// \since Crypto++ 6.0
6 /// \sa <A HREF="http://www.cryptopp.com/wiki/VIA_Padlock">VIA
7 /// Padlock</A> on the Crypto++ wiki
8 
9 #ifndef CRYPTOPP_PADLOCK_RNG_H
10 #define CRYPTOPP_PADLOCK_RNG_H
11 
12 #include "cryptlib.h"
13 #include "secblock.h"
14 
15 NAMESPACE_BEGIN(CryptoPP)
16 
17 /// \brief Exception thrown when a PadlockRNG generator encounters
18 /// a generator related error.
19 /// \since Crypto++ 6.0
20 class PadlockRNG_Err : public Exception
21 {
22 public:
23  PadlockRNG_Err(const std::string &operation)
24  : Exception(OTHER_ERROR, "PadlockRNG: " + operation + " operation failed") {}
25  PadlockRNG_Err(const std::string &component, const std::string &message)
26  : Exception(OTHER_ERROR, component + ": " + message) {}
27 };
28 
29 /// \brief Hardware generated random numbers using VIA XSTORE
30 /// \details Some VIA processors provide a Security Engine called Padlock. The Padlock
31 /// Security Engine provides AES, SHA and a RNG. The PadlockRNG class provides access
32 /// to the RNG.
33 /// \details The VIA generator uses an 8 byte FIFO buffer for random numbers. The
34 /// generator can be configured to discard bits from the buffer to resist analysis.
35 /// The <tt>divisor</tt> controls the number of bytes discarded. The formula for
36 /// the discard amount is <tt>2**divisor - 1</tt>. When <tt>divisor=0</tt> no bits
37 /// are discarded and the entire 8 byte buffer is read. If <tt>divisor=3</tt> then
38 /// 7 bytes are discarded and 1 byte is read. TheVIA SDK samples use <tt>divisor=1</tt>.
39 /// \details Cryptography Research, Inc (CRI) audited the Padlock Security Engine
40 /// in 2003. CRI provided recommendations to operate the generator for secure and
41 /// non-secure applications. Additionally, the Programmers Guide and SDK provided a
42 /// different configuration in the sample code.
43 /// \details You can operate the generator according to CRI recommendations by setting
44 /// <tt>divisor</tt>, reading one word (or partial word) at a time from the FIFO, and
45 /// then inspecting the MSR after each read.
46 /// \details The audit report with recommendations is available on the Crypto++ wiki
47 /// at <A HREF="http://www.cryptopp.com/wiki/VIA_Padlock">VIA Padlock</A>.
48 /// \sa MaurerRandomnessTest() for random bit generators
49 /// \since Crypto++ 6.0
51 {
52 public:
53  CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName() { return "PadlockRNG"; }
54 
55  virtual ~PadlockRNG() {}
56 
57  /// \brief Construct a PadlockRNG generator
58  /// \param divisor the XSTORE divisor
59  /// \details Some VIA processors provide a Security Engine called Padlock. The Padlock
60  /// Security Engine provides AES, SHA and a RNG. The PadlockRNG class provides access
61  /// to the RNG.
62  /// \details The VIA generator uses an 8 byte FIFO buffer for random numbers. The
63  /// generator can be configured to discard bits from the buffer to resist analysis.
64  /// The <tt>divisor</tt> controls the number of bytes discarded. The formula for
65  /// the discard amount is <tt>2**divisor - 1</tt>. When <tt>divisor=0</tt> no bits
66  /// are discarded and the entire 8 byte buffer is read. If <tt>divisor=3</tt> then
67  /// 7 bytes are discarded and 1 byte is read. VIA SDK samples use <tt>divisor=1</tt>.
68  /// \details Cryptography Research, Inc (CRI) audited the Padlock Security Engine
69  /// in 2003. CRI provided recommendations to operate the generator for secure and
70  /// non-secure applications. Additionally, the Programmers SDK provided a different
71  /// configuration in the sample code.
72  /// \details The audit report with recommendations is available on the Crypto++ wiki
73  /// at <A HREF="http://www.cryptopp.com/wiki/VIA_Padlock">VIA Padlock</A>.
74  /// \sa SetDivisor, GetDivisor
75  PadlockRNG(word32 divisor=1);
76 
77  /// \brief Generate random array of bytes
78  /// \param output the byte buffer
79  /// \param size the length of the buffer, in bytes
80  virtual void GenerateBlock(byte *output, size_t size);
81 
82  /// \brief Generate and discard n bytes
83  /// \param n the number of bytes to generate and discard
84  /// \details the Padlock generator discards words, not bytes. If n is
85  /// not a multiple of a 32-bit word, then it is rounded up to
86  /// that size.
87  virtual void DiscardBytes(size_t n);
88 
89  /// \brief Update RNG state with additional unpredictable values
90  /// \param input unused
91  /// \param length unused
92  /// \details The operation is a nop for this generator.
93  virtual void IncorporateEntropy(const byte *input, size_t length)
94  {
95  // Override to avoid the base class' throw.
96  CRYPTOPP_UNUSED(input); CRYPTOPP_UNUSED(length);
97  }
98 
99  std::string AlgorithmProvider() const;
100 
101  /// \brief Set the XSTORE divisor
102  /// \param divisor the XSTORE divisor
103  /// \return the old XSTORE divisor
105  {
106  word32 old = m_divisor;
107  m_divisor = DivisorHelper(divisor);
108  return old;
109  }
110 
111  /// \brief Get the XSTORE divisor
112  /// \return the current XSTORE divisor
114  {
115  return m_divisor;
116  }
117 
118  /// \brief Get the MSR for the last operation
119  /// \return the MSR for the last read operation
120  word32 GetMSR() const
121  {
122  return m_msr;
123  }
124 
125 protected:
126  inline word32 DivisorHelper(word32 divisor)
127  {
128  return divisor > 3 ? 3 : divisor;
129  }
130 
131 private:
133  word32 m_divisor, m_msr;
134 };
135 
136 NAMESPACE_END
137 
138 #endif // CRYPTOPP_PADLOCK_RNG_H
FixedSizeAlignedSecBlock< word32, 4, true >
secblock.h
Classes and functions for secure memory allocations.
PadlockRNG::PadlockRNG
PadlockRNG(word32 divisor=1)
Construct a PadlockRNG generator.
Definition: padlkrng.cpp:25
PadlockRNG::GetMSR
word32 GetMSR() const
Get the MSR for the last operation.
Definition: padlkrng.h:120
word32
unsigned int word32
32-bit unsigned datatype
Definition: config_int.h:62
PadlockRNG::GetDivisor
word32 GetDivisor() const
Get the XSTORE divisor.
Definition: padlkrng.h:113
RandomNumberGenerator
Interface for random number generators.
Definition: cryptlib.h:1434
Exception
Base class for all exceptions thrown by the library.
Definition: cryptlib.h:158
PadlockRNG
Hardware generated random numbers using VIA XSTORE.
Definition: padlkrng.h:50
CryptoPP
Crypto++ library namespace.
PadlockRNG::AlgorithmProvider
std::string AlgorithmProvider() const
Retrieve the provider of this algorithm.
Definition: padlkrng.cpp:20
PadlockRNG::DiscardBytes
virtual void DiscardBytes(size_t n)
Generate and discard n bytes.
Definition: padlkrng.cpp:91
PadlockRNG::IncorporateEntropy
virtual void IncorporateEntropy(const byte *input, size_t length)
Update RNG state with additional unpredictable values.
Definition: padlkrng.h:93
PadlockRNG::SetDivisor
word32 SetDivisor(word32 divisor)
Set the XSTORE divisor.
Definition: padlkrng.h:104
cryptlib.h
Abstract base classes that provide a uniform interface to this library.
PadlockRNG::GenerateBlock
virtual void GenerateBlock(byte *output, size_t size)
Generate random array of bytes.
Definition: padlkrng.cpp:34
PadlockRNG_Err
Exception thrown when a PadlockRNG generator encounters a generator related error.
Definition: padlkrng.h:20