org.randomness
Class TruerandomnessSharedLock

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

public class TruerandomnessSharedLock
extends Truerandomness


Constructor Summary
TruerandomnessSharedLock()
           
 
Method Summary
 void close()
          The uninstantiate function zeroizes (i.e., erases) the internal state of TRNG (possibly close the entropy source).
 boolean isOpen()
          Tells whether or not this TRNG entropy source is open.
 int minlen()
          Minlen is the minimum block of bytes essentially produced per one iteration of generate function (optional operation).
 int read(java.nio.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.
 void reset()
          The instantiate function determines the initial internal state of TRNG using the instantiate algorithm (possibly opens the entropy source).
 java.lang.String toString()
          Returns the name of the algorithm (or process) implemented by this RBG object (optional operation).
 int tryRead(java.nio.ByteBuffer buffer)
          Attempts to read from this RBG into the given buffer, if generate function is not owned by other thread.
 
Methods inherited from class org.randomness.Truerandomness
current, equals, fromCOMM, fromUSB, hashCode, readAssessment, readConditionally, reset, shared, test
 
Methods inherited from class org.randomness.Randomness
asRandom, bind, map, mixing, newBuffer, nextBoolean, nextByte, nextChar, nextCharASCII, nextDouble, nextFloat, nextHexString, nextInt, nextInt, nextLong, nextLong, nextProbability, nextShort, read, read, read, readFuture, readSink, reversed, shuffle
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

TruerandomnessSharedLock

public TruerandomnessSharedLock()
Method Detail

reset

public void reset()
Description copied from class: Truerandomness
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 Truerandomness

read

public int read(java.nio.ByteBuffer buffer)
Description copied from class: Truerandomness
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 java.nio.channels.ReadableByteChannel
Specified by:
read in class Truerandomness
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.

close

public void close()
Description copied from class: Truerandomness
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 java.io.Closeable
Specified by:
close in interface java.nio.channels.Channel
Specified by:
close in class Truerandomness

isOpen

public boolean isOpen()
Description copied from class: Truerandomness
Tells whether or not this TRNG entropy source is open.

Specified by:
isOpen in interface java.nio.channels.Channel
Specified by:
isOpen in class Truerandomness

tryRead

public int tryRead(java.nio.ByteBuffer buffer)
Description copied from class: Randomness
Attempts to read from this RBG into the given buffer, if generate function is not owned by other thread.

This method behaves exactly as specified in the generate function except that returns immediately if generate function is owned by other thread.

Specified by:
tryRead in class Randomness
Parameters:
buffer - The buffer into which random bytes are to be transferred.
Returns:
The number of bytes read from RBG, possibly zero, or -1 if the RBG is owned by other thread.

toString

public java.lang.String toString()
Description copied from class: Randomness
Returns the name of the algorithm (or process) implemented by this RBG object (optional operation).

In general case, toString description can contain all necessary information about RNG. If type of current RBG is undefined use UNKNOWN as type mark instead.

Specified by:
toString in class Randomness
Returns:
the name of the algorithm, or UNKNOWN if the algorithm name cannot be determined.

minlen

public int minlen()
Description copied from class: Randomness
Minlen is the minimum block of bytes essentially produced per one iteration of generate function (optional operation).

This method may provide additional information about generator to configure generation process more essential for generator. For example, this method should used as follows:

Randomness rnd = Cryptorandomness.from(CSPRNG.SHA1);
ByteBuffer buffer = ByteBuffer.allocate(rnd.minlen() * MULTIPLIER);
rnd.read(buffer); // essential for generator. may be optimized.

Specified by:
minlen in class Randomness
Returns:
number of bytes generated by RBG per one iteration