PRNG Class Reference

#include <rand.h>

Inheritance diagram for PRNG:

Collaboration diagram for PRNG:

---

Detailed Description

Implementation of the NIST FIPS 186-2 Pseudorandom Number Generator.

Class PRNG implements the SHA-1 based pseudorandom number generator of FIPS 186-2. The CDK also provides other pseudorandom number generators.

The most efficient way to use PRNG is:

• Instantiate a single PRNG object, and share it among multiple threads (using appropriate mutexes to ensure that two threads don't attempt to update the PRNG state simultaneously).

• Call PRNG::add() when desired to provide additional entropy that supplements the system state information it gathers automatically.

• Use the optional callback parameter to the PRNG constructor to maintain a persistent copy of the PRNG state. Storing the copy in a disk file or in the Windows registry makes it available to multiple applications or threads. (Again, mutexes should be used to ensure that no two threads attempt to update it at the same time).

Usage flow:
  PRNG()         // instantiate a new PRNG object
  add()          // [optional] add additional entropy
  addseed()      // [optional] add entropy to the starting seed 
  gens(), gen()  // obtain as many pseudorandom bytes as required


Recommendations for strict FIPS 140-1 compliance:
  Only gens(), gen(), or getrand2() may be called to obtain a random number
  used for cryptographic purposes. In other words, if you need to generate 
  a symmetric key, do *not* use genbasic() or getrand1()!
  
Calling churn(), genbasic(), setSeed(), mytime1(), or getrand1() directly 
is a violation of the FIPS 140-1 Security Policy for this CDK. These 
methods should be treated as private. 

Sample code illustrating the use of this class appears in the Cookbook section Pseudorandom Numbers.

NOTE: The CDK also provides two stateless random number generators via the global functions getrand1() and getrand2(). getrand1() is a rather unsophisticated RNG intendend only for internal use in non-cryptographic applications; it is not FIPS 140-1 compliant. getrand1(n) returns an n-byte string obtained by repeated calls to Random32() (which maintains a rather pitiful 32-bit state vector). getrand2() is a somewhat fancier RNG that uses a temporary instantiation of PRNG.

References

NIST specified pseudorandom number generators in FIPS 186-2, FIPS 140-2 Annex C, and NIST SP800-22.

Public Member Functions
	PRNG (int(*f)(str &)=0)
	Constructor.
virtual	~PRNG ()
	Destructor that zeroizes internal state data.
void	add (int n, const char *s)
	Update object's internal state vector with additional entropy.
str	gens (int n)
	Get a specified number of random bytes and update object's state vector.
num	gen (const num &modulus)
	Get a random integer less than a specified modulus and update object's state vector.
Internal Functions
These functions are declared public, but are intended for internal use only. FIPS 140-1 compliant applications may not use the methods and/or data members in this section. These functions can be used to reproduce the example in NIST FIPS 186-2 App. 5. (Function genbasic() is used by gens().)
void	setSeed (str &x)
	Specify a new seed value for this object; for internal use only.
void	addSeed (const str &x)
	Update internal seed value based on supplied input; for internal use only.
void	churn ()
	Update internal state vector using system state information as additional entropy.
str	genbasic (int iter)
	Basic pseudorandom number generator; for internal use only.

---

Constructor & Destructor Documentation

PRNG

(

int(*)(str &)

f = 0

)

[inline, explicit]

Constructor.

Parameters:

f

an optional callback function which is to be passed each generated random number. (A callback mechanism to provide additional entropy may be added in the future.)

---

Member Function Documentation

void add	(	int	n,
		const char *	s
	)

Update object's internal state vector with additional entropy.

Parameters:

	n	the number of bytes in the input buffer
	s	a pointer to the input buffer

void addSeed

(

const str &

x

)

Update internal seed value based on supplied input; for internal use only.

Parameters:

x

a str containing the data to be added to the seed.

Note:

The internal seed value is set to 0 by the constructor, so this can be used to set the seed to a specified value. Subsequent calls add x to the seed rather than resetting it. Since gens()/gen() call churn(), system state information is always factored in as additional entropy, so explicit calls to this method are not required.

void churn

(

)

Update internal state vector using system state information as additional entropy.

Remarks:

Calling churn() reseeds the PRNG with random system state information. Additional, user-supplied entropy can be input by calling add(). Explicit calls to these functions, however, are not really necessary as churn() is called automatically as random numbers are pulled from the PRNG object.

num gen

(

const num &

modulus

)

Get a random integer less than a specified modulus and update object's state vector.

Parameters:

modulus

the number that the generated random number must be less than

Returns:

a num containing a random number less than modulus

str genbasic

(

int

iter

)

Basic pseudorandom number generator; for internal use only.

Parameters:

iter

a mechanism selector or interation count: 1 for the mechanism of FIPS 186-2, Appendix 3.1 2 for the changes recommended by NIST on Aug. 2001 a positive integer larger than 2 results in a larger output string (see Returns section for details)

Returns:

a str containing (iter * 160) random bits, or an empty str if the CDK is in its hard error state

Note:

This function is for internal use only! It is used by class Key for DSA key generation in compliance with FIPS 186-2.

str gens

(

int

n

)

Get a specified number of random bytes and update object's state vector.

Parameters:

n

the number of random bytes to generate

Returns:

a str containing n random bytes

void setSeed

(

str &

x

)

[inline]

Specify a new seed value for this object; for internal use only.

Parameters:

x

the new initial seed value

Note:

This function is for internal use only! It is used by class Key for DSA key generation in compliance with FIPS 186-2.

---

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

• rand.h

---

ISC Cryptographic Development Kit - User's Guide
Questions? E-mail ISC technical support
Copyright© 2002-2006 Information Security Corp. All rights reserved.