Class CSPRNG

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.

Field Value:

"gnu.crypto.prng.pool.blocking"

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.

Field Value:

"gnu.crypto.prng.pool.files"

See Also:

SimpleList

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.

Field Value:

"gnu.crypto.prng.pool.other"

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.

Field Value:

"gnu.crypto.prng.pool.programs"

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.

Field Value:

"gnu.crypto.prng.pool.urls"

public CSPRNG()

The basic constructor. Object is special, because it has no superclass, so there is no call to super().

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 interface BasePRNG

Parameters:

b - The byte to add.

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 interface 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.

public Object clone()

This method may be called to create a new copy of the Object. The typical behavior is as follows:

• o == o.clone() is false
• o.getClass() == o.clone().getClass() is true
• o.equals(o) is true

However, these are not strict requirements, and may be violated if necessary. Of the three requirements, the last is the most commonly violated, particularly if the subclass does not override Object.equals(Object).

If the Object you call clone() on does not implement Cloneable (which is a placeholder interface), then a CloneNotSupportedException is thrown. Notice that Object does not implement Cloneable; this method exists as a convenience for subclasses that do.

Object's implementation of clone allocates space for the new Object using the correct class, without calling any constructors, and then fills in all of the new field values with the old field values. Thus, it is a shallow copy. However, subclasses are permitted to make a deep copy.

All array types implement Cloneable, and override this method as follows (it should never fail):

 public Object clone()
 {
   try
     {
       super.clone();
     }
   catch (CloneNotSupportedException e)
     {
       throw new InternalError(e.getMessage());
     }
 }
 

Specified by:

clone in interface IRandom

Overrides:

clone in interface BasePRNG

Returns:

a copy of the Object

See Also:

Cloneable

public void fillBlock()
            throws LimitReachedException

Overrides:

fillBlock in interface BasePRNG

protected void finalize()
            throws Throwable

Called on an object by the Virtual Machine at most once, at some point after the Object is determined unreachable but before it is destroyed. You would think that this means it eventually is called on every Object, but this is not necessarily the case. If execution terminates abnormally, garbage collection does not always happen. Thus you cannot rely on this method to always work. For finer control over garbage collection, use references from the java.lang.ref package.

Virtual Machines are free to not call this method if they can determine that it does nothing important; for example, if your class extends Object and overrides finalize to do simply super.finalize().

finalize() will be called by a Thread that has no locks on any Objects, and may be called concurrently. There are no guarantees on the order in which multiple objects are finalized. This means that finalize() is usually unsuited for performing actions that must be thread-safe, and that your implementation must be use defensive programming if it is to always work.

If an Exception is thrown from finalize() during garbage collection, it will be patently ignored and the Object will still be destroyed.

It is allowed, although not typical, for user code to call finalize() directly. User invocation does not affect whether automatic invocation will occur. It is also permitted, although not recommended, for a finalize() method to "revive" an object by making it reachable from normal code again.

Unlike constructors, finalize() does not get called for an object's superclass unless the implementation specifically calls super.finalize().

The default implementation does nothing.

Overrides:

finalize in interface Object

Throws:

Throwable - permits a subclass to throw anything in an overridden version; but the default throws nothing

See Also:

System.gc(), System.runFinalizersOnExit(boolean), java.lang.ref

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:

FILE_SOURCES

quality ; offset ; count ; path

FILE_SOURCES

URL_SOURCESpath

PROGRAM_SOURCES

OTHER_SOURCESEntropySource

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
 

public void setup(Map<K,V> attrib)

Overrides:

setup in interface BasePRNG