PadlockRNG Class Reference

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

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 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 | GenerateIntoBufferedTransformation (BufferedTransformation &target, const std::string &channel, lword length)
| Generate random bytes into a BufferedTransformation. 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...
Public Member Functions inherited from Clonable
virtual Clonable * | Clone () 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()

PadlockRNG::PadlockRNG | ( | word32 | divisor = `1` | ) |

Construct a PadlockRNG generator.

Parameters

  divisor | the 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

## GenerateBlock()

void PadlockRNG::GenerateBlock | ( | byte * | output,
|  | size_t | size
| ) |  |

virtual

Generate random array of bytes.

Parameters

  output | the byte buffer
  size | the 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

  n | the 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
| ) |  |

inline virtual

Update RNG state with additional unpredictable values.

Parameters

  input | unused
  length | unused

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

  divisor | the 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:

- padlkrng.h
- padlkrng.cpp