Crypto++ 8.7
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
15NAMESPACE_BEGIN(CryptoPP)
16
17/// \brief Exception thrown when a PadlockRNG generator encounters
18/// a generator related error.
19/// \since Crypto++ 6.0
21{
22public:
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{
52public:
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
121 {
122 return m_msr;
123 }
124
125protected:
126 inline word32 DivisorHelper(word32 divisor)
127 {
128 return divisor > 3 ? 3 : divisor;
129 }
130
131private:
133 word32 m_divisor, m_msr;
134};
135
136NAMESPACE_END
137
138#endif // CRYPTOPP_PADLOCK_RNG_H
Base class for all exceptions thrown by the library.
Definition: cryptlib.h:159
Exception thrown when a PadlockRNG generator encounters a generator related error.
Definition: padlkrng.h:21
Hardware generated random numbers using VIA XSTORE.
Definition: padlkrng.h:51
PadlockRNG(word32 divisor=1)
Construct a PadlockRNG generator.
Definition: padlkrng.cpp:25
virtual void DiscardBytes(size_t n)
Generate and discard n bytes.
Definition: padlkrng.cpp:91
virtual void GenerateBlock(byte *output, size_t size)
Generate random array of bytes.
Definition: padlkrng.cpp:34
word32 GetMSR() const
Get the MSR for the last operation.
Definition: padlkrng.h:120
word32 GetDivisor() const
Get the XSTORE divisor.
Definition: padlkrng.h:113
virtual void IncorporateEntropy(const byte *input, size_t length)
Update RNG state with additional unpredictable values.
Definition: padlkrng.h:93
std::string AlgorithmProvider() const
Retrieve the provider of this algorithm.
Definition: padlkrng.cpp:20
word32 SetDivisor(word32 divisor)
Set the XSTORE divisor.
Definition: padlkrng.h:104
Interface for random number generators.
Definition: cryptlib.h:1435
unsigned int word32
32-bit unsigned datatype
Definition: config_int.h:62
Abstract base classes that provide a uniform interface to this library.
Crypto++ library namespace.
Classes and functions for secure memory allocations.