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 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()

virtual PadlockRNG::~PadlockRNG ( )

inlinevirtual

Definition at line 55 of file padlkrng.h.

◆ 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

◆ 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

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
	)

inlinevirtual

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:

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~PadlockRNG()

◆ PadlockRNG()

Member Function Documentation

◆ StaticAlgorithmName()

◆ GenerateBlock()

◆ DiscardBytes()

◆ IncorporateEntropy()

◆ AlgorithmProvider()

◆ SetDivisor()

◆ GetDivisor()

◆ GetMSR()