For the latest news and information visit
The GNU Crypto project

gnu.crypto.prng
Class CSPRNG

java.lang.Object
  extended bygnu.crypto.prng.BasePRNG
      extended bygnu.crypto.prng.CSPRNG
All Implemented Interfaces:
Cloneable, IRandom

public class CSPRNG
extends BasePRNG

An entropy pool-based pseudo-random number generator based on the PRNG in Peter Gutmann's cryptlib (http://www.cs.auckland.ac.nz/~pgut001/cryptlib/).

The basic properties of this generator are:

  1. The internal state cannot be determined by knowledge of the input.
  2. It is resistant to bias introduced by specific inputs.
  3. The output does not reveal the state of the generator.


Field Summary
static String BLOCKING
          Property name for whether or not to wait for the slow poll to complete, passed as a Boolean.
static String FILE_SOURCES
          Property name for the list of files to read for random values.
static String OTHER_SOURCES
          Property name for a list of other sources of entropy.
static String PROGRAM_SOURCES
          Property name for the list of programs to execute, and use the output as new random bytes.
static String URL_SOURCES
          Property name for the list of URLs to poll for random values.
 
Fields inherited from class gnu.crypto.prng.BasePRNG
buffer, initialised, name, ndx
 
Constructor Summary
CSPRNG()
           
 
Method Summary
(package private)  void addQuality(double quality)
           
 void addRandomByte(byte b)
          Add a single random byte to the randomness pool.
 void addRandomBytes(byte[] buf, int off, int len)
          Add an array of bytes into the randomness pool.
 Object clone()
          Returns a clone copy of this instance.
 void fillBlock()
           
protected  void finalize()
           
(package private)  double getQuality()
           
static IRandom getSystemInstance()
          Create and initialize a CSPRNG instance with the "system" parameters; the files, URLs, programs, and EntropySource sources used by the instance are derived from properties set in the system Properties.
 void setup(Map attrib)
           
 
Methods inherited from class gnu.crypto.prng.BasePRNG
addRandomBytes, init, isInitialised, name, nextByte, nextBytes, nextBytes
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

FILE_SOURCES

public static final String FILE_SOURCES
Property name for the list of files to read for random values. The mapped value is a list with the following values:
  1. A Double, indicating the suggested quality of this source. This value must be between 0 and 100.
  2. An Integer, indicating the number of bytes to skip in the file before reading bytes. This can be any nonnegative value.
  3. An Integer, indicating the number of bytes to read.
  4. A String, indicating the path to the file.

See Also:
SimpleList, Constant Field Values

URL_SOURCES

public static final String URL_SOURCES
Property name for the list of URLs to poll for random values. The mapped value is a list formatted similarly as in FILE_SOURCES, but the fourth member is a URL.

See Also:
Constant Field Values

PROGRAM_SOURCES

public static final String PROGRAM_SOURCES
Property name for the list of programs to execute, and use the output as new random bytes. The mapped property is formatted similarly an in FILE_SOURCES and URL_SOURCES, except the fourth member is a String of the program to execute.

See Also:
Constant Field Values

OTHER_SOURCES

public static final String OTHER_SOURCES
Property name for a list of other sources of entropy. The mapped value must be a list of EntropySource objects.

See Also:
Constant Field Values

BLOCKING

public static final String BLOCKING
Property name for whether or not to wait for the slow poll to complete, passed as a Boolean. The default value is true.

See Also:
Constant Field Values
Constructor Detail

CSPRNG

public CSPRNG()
Method Detail

getSystemInstance

public static IRandom getSystemInstance()
                                 throws ClassNotFoundException,
                                        MalformedURLException,
                                        NumberFormatException

Create and initialize a CSPRNG instance with the "system" parameters; the files, URLs, programs, and EntropySource sources used by the instance are derived from properties set in the system Properties.

All properties are of the from name.N, where name is the name of the source, and N is an integer (staring at 1) that indicates the preference number for that source.

The following vales for name are used here:

gnu.crypto.csprng.file

These properties are file sources, passed as the FILE_SOURCES parameter of the instance. The property value is a 4-tuple formatted as:

quality ; offset ; count ; path

The parameters are mapped to the parameters defined for FILE_SOURCES. Leading or trailing spaces on any item are trimmed off.

gnu.crypto.csprng.url

These properties are URL sources, passed as the URL_SOURCES parameter of the instance. The property is formatted the same way as file sources, but the path argument must be a valid URL.

gnu.crypto.csprng.program

These properties are program sources, passed as the PROGRAM_SOURCES parameter of the instance. This property is formatted the same way as file and URL sources, but the last argument is a program and its arguments.

gnu.crypto.cspring.other

These properties are other sources, passed as the OTHER_SOURCES parameter of the instance. The property value must be the full name of a class that implements the EntropySource interface and has a public no-argument constructor.

Finally, a boolean property "gnu.crypto.csprng.blocking" can be set to the desired value of BLOCKING.

An example of valid properties would be:

 gnu.crypto.csprng.blocking=true

 gnu.crypto.csprng.file.1=75.0;0;256;/dev/random
 gnu.crypto.csprng.file.2=10.0;0;100;/home/user/file

 gnu.crypto.csprng.url.1=5.0;0;256;http://www.random.org/cgi-bin/randbyte?nbytes=256
 gnu.crypto.csprng.url.2=0;256;256;http://slashdot.org/

 gnu.crypto.csprng.program.1=0.5;0;10;last -n 50
 gnu.crypto.csprng.program.2=0.5;0;10;tcpdump -c 5

 gnu.crypto.csprng.other.1=foo.bar.MyEntropySource
 gnu.crypto.csprng.other.2=com.company.OtherEntropySource
 

Throws:
ClassNotFoundException
MalformedURLException
NumberFormatException

clone

public Object clone()
Description copied from interface: IRandom

Returns a clone copy of this instance.

Specified by:
clone in interface IRandom
Overrides:
clone in class BasePRNG

setup

public void setup(Map attrib)
Specified by:
setup in class BasePRNG

fillBlock

public void fillBlock()
               throws LimitReachedException
Specified by:
fillBlock in class BasePRNG
Throws:
LimitReachedException

addRandomBytes

public void addRandomBytes(byte[] buf,
                           int off,
                           int len)
Add an array of bytes into the randomness pool. Note that this method will not increment the pool's quality counter (this can only be done via a source provided to the setup method).

Specified by:
addRandomBytes in interface IRandom
Overrides:
addRandomBytes in class BasePRNG
Parameters:
buf - The byte array.
off - The offset from whence to start reading bytes.
len - The number of bytes to add.
Throws:
ArrayIndexOutOfBoundsException - If off or len are out of the range of buf.

addRandomByte

public void addRandomByte(byte b)
Add a single random byte to the randomness pool. Note that this method will not increment the pool's quality counter (this can only be done via a source provided to the setup method).

Specified by:
addRandomByte in interface IRandom
Overrides:
addRandomByte in class BasePRNG
Parameters:
b - The byte to add.

addQuality

void addQuality(double quality)

getQuality

double getQuality()

finalize

protected void finalize()
                 throws Throwable
Throws:
Throwable

For the latest news and information visit
The GNU Crypto project

Copyright © 2001, 2002, 2003 Free Software Foundation, Inc. All Rights Reserved.