org.randomness
Class Truerandomness

java.lang.Object
  extended by org.randomness.Randomness
      extended by org.randomness.Truerandomness
All Implemented Interfaces:
Closeable, Channel, ReadableByteChannel, ScatteringByteChannel

public abstract class Truerandomness
extends Randomness

This class specifies True Random Number Generator (TRNG) techniques for the reading high quality, unpredictable random bytes from the specified entropy source.

The best way to obtain truly random bits would be to observe a atomic or subatomic physical phenomenon which is believed to exhibit random behavior. Possible sources of entropy include radioactive decay, thermal noise, shot noise, avalanche noise in Zener diodes, clock drift, the timing of actual movements of a hard disk read/write head, and radio noise. Also, some computational things can be used, such a thread synchronization. However, physical phenomena and tools used to measure them generally feature asymmetries and systematic biases that make their outcomes not uniformly random. A randomness extractor, such as a cryptographic hash function, can be used to obtain uniformly distributed bits from a non-uniformly random source, though at a lower bit rate.

TRNG is suitable to use in cryptography. Problems of TRNG is that they usually not fast enough. Some applications need to generate millions of random numbers as quickly as possible. For this purposes Pseudorandom Number Generators or Cryptographically Secure Pseudorandom Number Generators can be used.

TRNG mechanisms

This specification based on strongly limited version of NIST 800-90 adopted to describe mechanisms of True Random Number Generators (see Appendix C:(Normative) Entropy and Entropy Sources).

The TRNG mechanisms class have four separate functions to handle the TRNG’s internal state:

  1. The instantiate function determines the initial internal state of TRNG and open it for reading random bytes from entropy source. A TRNG shall be opened prior to the reading of random bits. Opposite to uninstantiate function.
  2. The generate function harvest random bits from entropy source per request, can determine entropy of requested bits (optional, if possible) and reduce to independent bits if requested bits has low quality entropy. RBG should be instantiateed before generation.
  3. The uninstantiate function close (i.e., erases) this TRNG. Opposite to instantiate function.
  4. The health test function shall be performed to determine that the TRNG mechanism is continuing to perform correctly.

TRNG Properties

TRNG Entropy source

Entropy is obtained from an entropy source. The entropy input required to seed or reseed a PRNG shall be obtained either directly or indirectly from an entropy source

Entropy source - a source of unpredictable data. There is no assumption that the unpredictable data has a uniform distribution. The entropy source includes a noise source, such as thermal noise or hard drive seek times; a digitization process; an assessment process; an optional conditioning process and health tests.

Conditioned Entropy Source - An entropy source that either includes a conditioning function or for which conditioning is performed on the output of the entropy source. The conditioning function ensures that the conditioned entropy source provides full entropy bitstrings, i.e. the entropy of the bitstring will be the same as its length. Health tests shall be performed to determine that the entropy source is continuing to perform correctly.

PROVISIONAL API, WORK IN PROGRESS

TODO:

  1. Interruptible generation
  2. Support of selectable, nonblocking and asynchronous reading
  3. Randomness extraction
  4. Login\password instantiation
  5. Entropy pools
  6. Testing truerandomness (testing buffer)
  7. Whitening strategies (John von Neumann and others)
  8. Estimating entropy (Entropy, Chi-square Test, Arithmetic Mean, Monte Carlo Value for Pi, Serial Correlation Coefficient)
  9. Hardware random number generators should be constantly monitored for proper operation. RFC 4086 and FIPS Pub 140-2 include tests which can be used for this.

Author:
Anton Kabysh - Code,
NIST 800-90 autors (Elaine Barker, John Kelsey) - Specification
See Also:
Wikipedia - Hardware random number generator,
Stackoverflow - What is the most secure seed for random number generation?,
About random bits (pdf)

Constructor Summary
protected Truerandomness()
          Default constructor.
 
Method Summary
abstract  void close()
          The uninstantiate function zeroizes (i.e., erases) the internal state of TRNG (possibly close the entropy source).
static Truerandomness current(TRNG source)
          Returns a unique True-random Number Generator isolated to the current thread (thread-local) associated with specified entropy source.
 boolean equals(Object obj)
          Indicates whether some other object is "equal to" this one.
static Truerandomness fromCOMM(String port)
          TODO PROVISIONAL API, WORK IN PROGRESS: Returns the specified True-random Number Generator using specified COMM connection as a source of entropy.
static Truerandomness fromUSB(String port)
          TODO PROVISIONAL API, WORK IN PROGRESS: Returns the specified True-random Number Generator using specified USB connection as a source of entropy.
 int hashCode()
          Returns the unique hash code value of this Truerandomness (consistent with equals).
abstract  boolean isOpen()
          Tells whether or not this TRNG entropy source is open.
abstract  int read(ByteBuffer buffer)
          The generate function harvest random bits from entropy source per request, can determine entropy of requested bits (optional) and reduce to independent bits if requested bits has low quality entropy.
 double readAssessment(ByteBuffer buffer)
          TODO PROVISIONAL API, WORK IN PROGRESS: Reads a sequence of bytes from specified entropy source returning the amount of actual entropy obtained from an entropy source.
 boolean readConditionally(ByteBuffer buffer, int min_entropy)
          TODO PROVISIONAL API, WORK IN PROGRESS: Reads a sequence of bytes from specified entropy source and the conditioning function ensures that the conditioned entropy source provides entropy bitstrings, with specified min_entropy.
abstract  void reset()
          The instantiate function determines the initial internal state of TRNG using the instantiate algorithm (possibly opens the entropy source).
 void reset(String login, String password)
          TODO PROVISIONAL API, WORK IN PROGRESS: Instantiate with specified login and password (for services with autorization such as random.org and QRBG ).
static Truerandomness shared(TRNG source)
          Returns a new shared Truerandom generator that implements the specified entropy gathering mechanism, or True Random Number Generator (TRNG).
 boolean test()
          TODO PROVISIONAL API, WORK IN PROGRESS: The health test function determines that the TRNG mechanism continues to function correctly; An implementation should provide a capability to test the instantiate function on demand.
 
Methods inherited from class org.randomness.Randomness
asRandom, bind, map, minlen, mixing, newBuffer, nextBoolean, nextByte, nextChar, nextCharASCII, nextDouble, nextFloat, nextHexString, nextInt, nextInt, nextLong, nextLong, nextProbability, nextShort, read, read, read, readFuture, readSink, reversed, shuffle, toString, tryRead
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Truerandomness

protected Truerandomness()
Default constructor.

Method Detail

reset

public abstract void reset()
The instantiate function determines the initial internal state of TRNG using the instantiate algorithm (possibly opens the entropy source). A TRNG shall be instantiated prior to the reading of random bits.

Opposite to uninstantiate function.

Specified by:
reset in class Randomness

reset

public void reset(String login,
                  String password)
TODO PROVISIONAL API, WORK IN PROGRESS: Instantiate with specified login and password (for services with autorization such as random.org and QRBG ).

Parameters:
login -
password -

read

public abstract int read(ByteBuffer buffer)
The generate function harvest random bits from entropy source per request, can determine entropy of requested bits (optional) and reduce to independent bits if requested bits has low quality entropy. In other words, reads a sequence harvested bytes from underlying entropy source into the given buffer. An attempt is made to read up to r bytes from TRNG, where r is the number of bytes remaining in the buffer, that is, buffer.remaining(), at the moment this method is invoked.

The process to obtain true-random bits from entropy source typically involves the following steps:

  1. Harvest bits - One first gathers some bits unknown to and unguessable by the adversary. These must come from some entropy source which is referred to a noise source.
  2. Determine entropy(optional) - The word “entropy” is used to describe a measure of randomness, i.e., a description of how hard a value is to guess. The second step is then to determine how many unguessable bits were thus harvested. Some entropy source are better than others in unguessability. But usually it is really hard to measure entropy of random input, so the better strategy to mix different entropy sources using hash mixing function.
  3. Reduce to independent bits (optional) - As a third step, one can compute a hash of the harvested bits to reduce them to independent, random bits. The hash function for this stage of operation needs to have each output bit functionally dependent on all input bits and functionally independent of all other output bits. Barring formal analysis, we assume that the hash functions which are claimed to be cryptographically strong (MD5 and SHA) have this characteristic.

Specified by:
read in interface ReadableByteChannel
Specified by:
read in class Randomness
Parameters:
buffer - The buffer into which entropy are to be transferred.
Returns:
The number of bytes read from TRNG, possibly zero, or -1 if the TRNG has reached end-of-stream.
Throws:
NullPointerException - if buffer is null.
NonReadableChannelException - If this TRNG was not opened for reading (is closed).

readConditionally

public boolean readConditionally(ByteBuffer buffer,
                                 int min_entropy)
TODO PROVISIONAL API, WORK IN PROGRESS: Reads a sequence of bytes from specified entropy source and the conditioning function ensures that the conditioned entropy source provides entropy bitstrings, with specified min_entropy.

Entropy tests shall be performed to determine that the entropy source is continuing to perform correctly.

Parameters:
buffer -
min_entropy - number bytes of entropy.
Returns:
true if returned transfered bytes contains enough entropy, false otherwise.

readAssessment

public double readAssessment(ByteBuffer buffer)
TODO PROVISIONAL API, WORK IN PROGRESS: Reads a sequence of bytes from specified entropy source returning the amount of actual entropy obtained from an entropy source.

See Appendix C:(Normative) Entropy and Entropy Sources. C.3 Entropy Assessment

Parameters:
buffer -
Returns:
the entropy measurement that is known as min-entropy (Hmin).

close

public abstract void close()
The uninstantiate function zeroizes (i.e., erases) the internal state of TRNG (possibly close the entropy source).

Opposite to instantiate function.

After a TRNG is closed, any further attempt to invoke read operations upon it will cause a NonReadableChannelException to be thrown.

If this TRNG is already closed then invoking this method has no effect. This method may be invoked at any time. If some other thread has already invoked it, however, then another invocation will block until the first invocation is complete, after which it will return without effect.

Specified by:
close in interface Closeable
Specified by:
close in interface Channel
Specified by:
close in class Randomness

isOpen

public abstract boolean isOpen()
Tells whether or not this TRNG entropy source is open.

Specified by:
isOpen in interface Channel
Specified by:
isOpen in class Randomness

shared

public static final Truerandomness shared(TRNG source)
Returns a new shared Truerandom generator that implements the specified entropy gathering mechanism, or True Random Number Generator (TRNG).

Parameters:
source - type of entropy source.
Returns:
a new shared Truerandomness entropy generator.

current

public static final Truerandomness current(TRNG source)
Returns a unique True-random Number Generator isolated to the current thread (thread-local) associated with specified entropy source. Any attempt to use this instance from another thread will throw ConcurrentModificationException.

Thread-local TRNG initializes when this method is first called; any further call will return the same instance for the same thread.

Parameters:
source - type of entropy source.
Returns:
a new thread-local Truerandom generator
See Also:
TRNG.current()

fromUSB

public static final Truerandomness fromUSB(String port)
TODO PROVISIONAL API, WORK IN PROGRESS: Returns the specified True-random Number Generator using specified USB connection as a source of entropy.

This method should be used to connect Truerandomness with Hardware random number generator connected to base station via USB.

Parameters:
port - the specified USB connection name.
See Also:
Hardware random number generator

fromCOMM

public static final Truerandomness fromCOMM(String port)
TODO PROVISIONAL API, WORK IN PROGRESS: Returns the specified True-random Number Generator using specified COMM connection as a source of entropy.

This method should be used to connect Truerandomness with Hardware random number generator connected to base station via COMM port.

Parameters:
port - the specified COMM connection name.
See Also:
Hardware random number generator

test

public boolean test()
TODO PROVISIONAL API, WORK IN PROGRESS: The health test function determines that the TRNG mechanism continues to function correctly; An implementation should provide a capability to test the instantiate function on demand.

Known-answer tests shall be performed on the generate function before the first use of the function in an implementation.

TODO:

  1. FIPS 140-1. statistical tests
  2. Collect entropy gathering tests
  3. Measurement of min-entropy (Hmin).

Returns:
true if entropy source perform correctly, false otherwise.

equals

public final boolean equals(Object obj)
Indicates whether some other object is "equal to" this one.

Overrides:
equals in class Object
Parameters:
obj - the reference object with which to compare.
Returns:
true if this object is the same as the obj argument; false otherwise.

hashCode

public final int hashCode()
Returns the unique hash code value of this Truerandomness (consistent with equals).

Overrides:
hashCode in class Object
Returns:
a hash code value for this object.