Crypto++ 8.7
Free C++ class library of cryptographic schemes
Public Member Functions | Static Public Member Functions | List of all members
PadlockRNG Class Reference

Hardware generated random numbers using VIA XSTORE. More...

#include <padlkrng.h>

+ Inheritance diagram for PadlockRNG:

Public Member Functions

 PadlockRNG (word32 divisor=1)
 Construct a PadlockRNG generator. More...
 
virtual void GenerateBlock (byte *output, size_t size)
 Generate random array of bytes. More...
 
virtual void DiscardBytes (size_t n)
 Generate and discard n bytes. More...
 
virtual void IncorporateEntropy (const byte *input, size_t length)
 Update RNG state with additional unpredictable values. More...
 
std::string AlgorithmProvider () const
 Retrieve the provider of this algorithm. More...
 
word32 SetDivisor (word32 divisor)
 Set the XSTORE divisor. More...
 
word32 GetDivisor () const
 Get the XSTORE divisor. More...
 
word32 GetMSR () const
 Get the MSR for the last operation. More...
 
- Public Member Functions inherited from RandomNumberGenerator
virtual void IncorporateEntropy (const byte *input, size_t length)
 Update RNG state with additional unpredictable values. More...
 
virtual bool CanIncorporateEntropy () const
 Determines if a generator can accept additional entropy. More...
 
virtual byte GenerateByte ()
 Generate new random byte and return it. More...
 
virtual unsigned int GenerateBit ()
 Generate new random bit and return it. More...
 
virtual word32 GenerateWord32 (word32 min=0, word32 max=0xffffffffUL)
 Generate a random 32 bit word in the range min to max, inclusive. More...
 
virtual void GenerateBlock (byte *output, size_t size)
 Generate random array of bytes. More...
 
virtual void GenerateIntoBufferedTransformation (BufferedTransformation &target, const std::string &channel, lword length)
 Generate random bytes into a BufferedTransformation. More...
 
virtual void DiscardBytes (size_t n)
 Generate and discard n bytes. More...
 
template<class IT >
void Shuffle (IT begin, IT end)
 Randomly shuffle the specified array. More...
 
- Public Member Functions inherited from Algorithm
 Algorithm (bool checkSelfTestStatus=true)
 Interface for all crypto algorithms. More...
 
virtual std::string AlgorithmName () const
 Provides the name of this algorithm. More...
 
virtual std::string AlgorithmProvider () const
 Retrieve the provider of this algorithm. More...
 
- Public Member Functions inherited from Clonable
virtual ClonableClone () const
 Copies this object. More...
 

Static Public Member Functions

static const char * StaticAlgorithmName ()
 

Detailed Description

Hardware generated random numbers using VIA XSTORE.

Some VIA processors provide a Security Engine called Padlock. The Padlock Security Engine provides AES, SHA and a RNG. The PadlockRNG class provides access to the RNG.

The VIA generator uses an 8 byte FIFO buffer for random numbers. The generator can be configured to discard bits from the buffer to resist analysis. The divisor controls the number of bytes discarded. The formula for the discard amount is 2**divisor - 1. When divisor=0 no bits are discarded and the entire 8 byte buffer is read. If divisor=3 then 7 bytes are discarded and 1 byte is read. TheVIA SDK samples use divisor=1.

Cryptography Research, Inc (CRI) audited the Padlock Security Engine in 2003. CRI provided recommendations to operate the generator for secure and non-secure applications. Additionally, the Programmers Guide and SDK provided a different configuration in the sample code.

You can operate the generator according to CRI recommendations by setting divisor, reading one word (or partial word) at a time from the FIFO, and then inspecting the MSR after each read.

The audit report with recommendations is available on the Crypto++ wiki at VIA Padlock.

See also
MaurerRandomnessTest() for random bit generators
Since
Crypto++ 6.0

Definition at line 50 of file padlkrng.h.

Constructor & Destructor Documentation

◆ ~PadlockRNG()

virtual PadlockRNG::~PadlockRNG ( )
inlinevirtual

Definition at line 55 of file padlkrng.h.

◆ PadlockRNG()

PadlockRNG::PadlockRNG ( word32  divisor = 1)

Construct a PadlockRNG generator.

Parameters
divisorthe XSTORE divisor

Some VIA processors provide a Security Engine called Padlock. The Padlock Security Engine provides AES, SHA and a RNG. The PadlockRNG class provides access to the RNG.

The VIA generator uses an 8 byte FIFO buffer for random numbers. The generator can be configured to discard bits from the buffer to resist analysis. The divisor controls the number of bytes discarded. The formula for the discard amount is 2**divisor - 1. When divisor=0 no bits are discarded and the entire 8 byte buffer is read. If divisor=3 then 7 bytes are discarded and 1 byte is read. VIA SDK samples use divisor=1.

Cryptography Research, Inc (CRI) audited the Padlock Security Engine in 2003. CRI provided recommendations to operate the generator for secure and non-secure applications. Additionally, the Programmers SDK provided a different configuration in the sample code.

The audit report with recommendations is available on the Crypto++ wiki at VIA Padlock.

See also
SetDivisor, GetDivisor

Definition at line 25 of file padlkrng.cpp.

Member Function Documentation

◆ StaticAlgorithmName()

static const char * PadlockRNG::StaticAlgorithmName ( )
inlinestatic

Definition at line 53 of file padlkrng.h.

◆ GenerateBlock()

void PadlockRNG::GenerateBlock ( byte output,
size_t  size 
)
virtual

Generate random array of bytes.

Parameters
outputthe byte buffer
sizethe length of the buffer, in bytes

Reimplemented from RandomNumberGenerator.

Definition at line 34 of file padlkrng.cpp.

◆ DiscardBytes()

void PadlockRNG::DiscardBytes ( size_t  n)
virtual

Generate and discard n bytes.

Parameters
nthe number of bytes to generate and discard

the Padlock generator discards words, not bytes. If n is not a multiple of a 32-bit word, then it is rounded up to that size.

Reimplemented from RandomNumberGenerator.

Definition at line 91 of file padlkrng.cpp.

◆ IncorporateEntropy()

virtual void PadlockRNG::IncorporateEntropy ( const byte input,
size_t  length 
)
inlinevirtual

Update RNG state with additional unpredictable values.

Parameters
inputunused
lengthunused

The operation is a nop for this generator.

Reimplemented from RandomNumberGenerator.

Definition at line 93 of file padlkrng.h.

◆ AlgorithmProvider()

std::string PadlockRNG::AlgorithmProvider ( ) const
virtual

Retrieve the provider of this algorithm.

Returns
the algorithm provider

The algorithm provider can be a name like "C++", "SSE", "NEON", "AESNI", "ARMv8" and "Power8". C++ is standard C++ code. Other labels, like SSE, usually indicate a specialized implementation using instructions from a higher instruction set architecture (ISA). Future labels may include external hardware like a hardware security module (HSM).

Generally speaking Wei Dai's original IA-32 ASM code falls under "SSE2". Labels like "SSSE3" and "SSE4.1" follow after Wei's code and use intrinsics instead of ASM.

Algorithms which combine different instructions or ISAs provide the dominant one. For example on x86 AES/GCM returns "AESNI" rather than "CLMUL" or "AES+SSE4.1" or "AES+CLMUL" or "AES+SSE4.1+CLMUL".

Note
Provider is not universally implemented yet.
Since
Crypto++ 8.0

Reimplemented from Algorithm.

Definition at line 20 of file padlkrng.cpp.

◆ SetDivisor()

word32 PadlockRNG::SetDivisor ( word32  divisor)
inline

Set the XSTORE divisor.

Parameters
divisorthe XSTORE divisor
Returns
the old XSTORE divisor

Definition at line 104 of file padlkrng.h.

◆ GetDivisor()

word32 PadlockRNG::GetDivisor ( ) const
inline

Get the XSTORE divisor.

Returns
the current XSTORE divisor

Definition at line 113 of file padlkrng.h.

◆ GetMSR()

word32 PadlockRNG::GetMSR ( ) const
inline

Get the MSR for the last operation.

Returns
the MSR for the last read operation

Definition at line 120 of file padlkrng.h.


The documentation for this class was generated from the following files: