|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.randomness.Randomness
public abstract class Randomness
This class specifies basic Random Bit Generator (RBG) life cycle and mechanisms for the generation of random bits.
A randomness represents an open connection to an entity such as a hardware device, or an deterministic algorithm that is capable of producing random output. Life cycle of Random Bit Generator inspired on NIST 800-90 Specification. The RBG mechanisms have four separate functions handle the RBG’s internal state:
The health test function determines that the DRBG mechanism continues to function correctly (optional).
Randomness can be represented in different views:
java.util.Random
instance.
XOR
mixing function.
Randomness
and reverses the order in each small window
of configurable size (byte-by-byte).
unmodifiable
view over this RBG.
As specified in the Channel
interface RBG are either open or closed,
and they are both asynchronously closeable and, in general, should
(intended) to be safe for multithreaded access.
Constructor Summary | |
---|---|
protected |
Randomness()
Default constructor. |
RBG Functions Summary | |
---|---|
abstract void |
reset()
The instantiate function determines the initial internal state of RBG using the instantiate algorithm. |
abstract int |
read(ByteBuffer dst)
The generate function generates the requested random bits using the generate algorithm. |
abstract void |
close()
The uninstantiate function zeroizes the internal state of RBG interrupting generate function, if proceed. |
Additional Operations Summary | |
---|---|
abstract boolean |
isOpen()
Tells whether or not this RBG is open to generate random bytes. |
abstract int |
minlen()
Minlen is the minimum block of bytes essentially produced per one iteration of generate function (optional operation). |
abstract String |
toString()
Returns the name of the algorithm (or process) implemented by this RBG object (optional operation). |
Read Methods Summary | |
---|---|
int |
read(byte[] bytes)
Transfers a sequence generated bytes from this RBG into the given array. |
long |
read(ByteBuffer[] dsts)
Reads a sequence of random bytes from this RBG into the given buffers. |
long |
read(ByteBuffer[] dsts,
int offset,
int length)
Reads a sequence of bytes from this RBG into a subsequence of the given buffers. |
abstract int |
tryRead(ByteBuffer buffer)
Attempts to read from this RNG into the given buffer, starting at the given file position if generate function is not owned by other thread. |
Future<Integer> |
readFuture(ByteBuffer dst)
PROVISIONAL API, WORK IN PROGRESS: Reads asynchronously sequence of bytes in non-blocking mode from this channel into the given buffer, retrieving result in the future when operation is done. |
Pipe.SourceChannel |
readSink(int bytes)
PROVISIONAL API, WORK IN PROGRESS: Reads a sequence of bytes in non-blocking mode from this channel into the Pipe.SourceChannel
(). |
Generation Methods Summary | |
---|---|
boolean |
nextBoolean()
Return's next generated random 1-bit boolean value (like
coin flip). |
byte |
nextByte()
Return's next generated random 8-bit byte value. |
char |
nextChar()
Return's next generated random unsigned 16-bit char value
UNICODE encoded. |
char |
nextCharASCII()
Return's next randomly generated 8-bit char value
US-ASCII encoded. |
double |
nextDouble()
Return's next generated random 64-bit floating-point double
value between 0.0 (inclusive) and 1.0
(exclusive). |
float |
nextFloat()
Return's next generated random 32-bit floating-point float
() value between 0.0 (inclusive) and 1.0
(exclusive). |
String |
nextHexString(int length)
Generates a random string of hex characters of specified length . |
int |
nextInt()
Return's next generated random 32-bit int value. |
int |
nextInt(int n)
Return's next generated random int value drawn uniformly
from 0 to n-1 . |
long |
nextLong()
Return's next generated random 64-bit long value. |
long |
nextLong(long n)
Return's next generated random long value drawn uniformly
from 0 to n-1 . |
boolean |
nextProbability(float probability)
Return's next generated boolean with a specified probability
of returning true , else returning false . |
short |
nextShort()
Return's next generated random 16-bit short () value
(typically from nextInt value returned two most significant
bytes). |
Views Summary | |
---|---|
Random |
asRandom()
Represents this RBG as java.util.Random . |
Randomness |
mixing(Randomness... randomness)
Returns new RBG represents mixing of this RBG with specified RBG's sequence using default XOR mixing function. |
Randomness |
reversed(int windowSize)
Takes bytes generated by an underling Randomness and
reverses the order in each small window of configurable size
(byte-by-byte). |
Randomness |
shuffle(Randomness that)
Shuffle uses one RBG to shuffle the output produced by another RBG to obliterate sequential correlations to produce non-linear output. |
Randomness |
bind(SocketAddress address)
PROVISIONAL API, WORK IN PROGRESS: Open a server associated with this RBG on specified port. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Constructor Detail |
---|
protected Randomness()
Method Detail |
---|
public static void map(String algorithm, Class<? extends Randomness> provider)
If a algorithm with the same name exist and it provider was previously added using map(), it is replaced by the new service.
algorithm
- the string constrains readable name of algorithm which is
producing randomness (possibly with provider prefix or suffix)provider
- the class-provider with default constructor implementing the
associated algorithm.
IllegalArgumentException
- if algorithm or provider is null
or if provider
does not have default constructor.public abstract boolean isOpen()
isOpen
in interface Channel
public abstract void reset()
If RBG has already initiated a generate operation, then an invocation of this method will block until the first operation is complete. If RBG already initiated a generate function, then an invocation of instantiate function will block until the generate operation is complete.
Opposite to uninstantiate function.
public abstract int read(ByteBuffer dst)
Transfers a sequence generated bytes from this RBG into the given buffer. An attempt is made to read up to r bytes from RBG, where r is the number of bytes remaining in the buffer, that is, buffer.remaining(), at the moment this method is invoked.
Suppose that a byte sequence of length n is read, where 0 <= n <= r. This byte sequence will be transferred into the buffer so that the first byte in the sequence is at index p and the last byte is at index p + n - 1, where p is the buffer's position at the moment this method is invoked. Upon return the buffer's position will be equal to p + n; its limit will not have changed. As many bytes as possible are transferred into each buffer, hence the final position is guaranteed to be equal to that buffer's limit. Also, a read operation might not fill the buffer, and in fact it might not read any bytes at all. Whether or not it does so depends upon the nature and state of the RBG.
This method may be invoked at any time. If another thread has already initiated a read operation upon this RBG, however, then an invocation of this method will block until the first operation is complete.
Calling uninstantiate function in interrupt this metod normally (without exceptions).
read
in interface ReadableByteChannel
dst
- The buffer into which random bytes are to be transferred.
NullPointerException
- if buffer
is null
.
NonReadableChannelException
- If this RBG was not opened for reading (is
closed).public final long read(ByteBuffer[] dsts)
Scattering reads are often useful when required to produce several fixed-length (or not) segments with randomness bytes. Also, some, especially fixed-length blocks generators can be much more efficient for scattering reads if block size is equal to minlen or multiply of it.
An invocation of this method of the form r.read(dsts) behaves in exactly the same manner as the invocation:
r.read(dsts, 0, dsts.length);
read
in interface ScatteringByteChannel
dsts
- The buffers into which bytes are to be transferred
NullPointerException
- if one of ByteBuffers in dsts
or array itself is
null
.
NonReadableChannelException
- If this RBG was not opened for reading.read(ByteBuffer)
public final long read(ByteBuffer[] dsts, int offset, int length)
An invocation of this method attempts to read up to r bytes from this RBG, where r is the total number of bytes remaining the specified subsequence of the given buffer array, that is,
at the moment that this method is invoked.dsts[offset].remaining() + dsts[offset+1].remaining() + ... + dsts[offset+length-1].remaining()
Suppose that a byte sequence of length n is read, where 0 <= n <= r. Up to the first dsts[offset].remaining() bytes of this sequence are transferred into buffer dsts[offset], up to the next dsts[offset+1].remaining() bytes are transferred into buffer dsts[offset+1], and so forth, until the entire byte sequence is transferred into the given buffers. As many bytes as possible are transferred into each buffer, hence the final position of each updated buffer, except the last updated buffer, is guaranteed to be equal to that buffer's limit.
This method may be invoked at any time. If another thread has already initiated a read operation upon this RBG, however, then an invocation of this method will block until the first operation is complete.
This method behaves exactly as specified in the generate function.
read
in interface ScatteringByteChannel
dsts
- The buffers into which bytes are to be transferredoffset
- The offset within the buffer array of the first buffer into
which bytes are to be transferred; must be non-negative and no
larger than dsts.lengthlength
- The maximum number of buffers to be accessed; must be
non-negative and no larger than dsts.length
- offset
IndexOutOfBoundsException
- If the preconditions on the offset and
length parameters do not hold.
NonReadableChannelException
- If this RBG was not opened for reading
NullPointerException
- if one of ByteBuffers in dsts
or array itself is
null
.public final int read(byte[] bytes)
This method behaves exactly as specified in the generate function.
bytes
- a byte array into which random bytes are to be transferred
NullPointerException
- if array is null
.read(ByteBuffer)
public final Future<Integer> readFuture(ByteBuffer dst)
dst
- destination buffer
Future
result.public abstract int tryRead(ByteBuffer buffer)
This method behaves exactly as specified in the generate function except that returns immediately if generate function is owned by other thread.
buffer
- The buffer into which random bytes are to be transferred.
public final Pipe.SourceChannel readSink(int bytes)
Pipe.SourceChannel
().
Source channel can be managaned by Selector
to do a readiness
selection of generated bytes.
bytes
- number of bytes to read
public final Randomness bind(SocketAddress address)
this
RBG on specified port.
address
-
this
public abstract void close()
After a RBG is closed, any further attempt to invoke
read operations upon it will
cause a NonReadableChannelException
to be thrown.
The closing status can be tested runtime via isOpen() method.
The closed status of the RBG is cleared by reset function.
close
in interface Closeable
close
in interface Channel
public abstract String toString()
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.
toString
in class Object
UNKNOWN
if the
algorithm name cannot be determined.public abstract int minlen()
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.
public boolean nextBoolean()
boolean
value (like
coin flip). Returned values are chosen pseudorandomly with
(approximately) uniform distribution from true
or
false
with equal probability.
It is important to remember, that boolean
values are hold in
platform dependent way (depends from JVM). For large boolean
arrays is better to use something like java.util.BitSet
.
boolean
value.
NonReadableChannelException
- If this RBG was not opened for generation.public final boolean nextProbability(float probability)
boolean
with a specified probability
of returning true
, else returning false
.
Uses 32-bit precision.
probability
- probability must be between 0.0 and 1.0, inclusive.
next
generatedpublic byte nextByte()
byte
value. Returned
values are chosen pseudorandomly with (approximately) uniform
distribution from range Byte.MIN_VALUE
to Byte.MAX_VALUE
.
-128..127
].
NonReadableChannelException
- If this RBG was not opened for generation.public short nextShort()
short
() value
(typically from nextInt
value returned two most significant
bytes).
short
value in range
[-32768..32767]
NonReadableChannelException
- If this RBG was not opened for generation.public final char nextChar()
char
value
UNICODE
encoded. Returned values are chosen pseudorandomly
with (approximately) uniform distribution from range
Character.MIN_VALUE
to Character.MAX_VALUE
.
Can be used instead of unsigned short.
char
value (2 byte
unicode
) in range [