Overview | Package | Class | Tree | Deprecated | Index | Help
| Oracle Security Developer Tools Crypto Java API Reference 10g Release 3 (10.1.3) B25378-01
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## oracle.security.crypto.core
Class DigestRandomBitsSource

`java.lang.Object
oracle.security.crypto.core.RandomBitsSource
oracle.security.crypto.core.DigestRandomBitsSource`

Direct Known Subclasses:
  MD5RandomBitsSource, SHA1RandomBitsSource

public abstract class DigestRandomBitsSource
extends RandomBitsSource

A PRNG based on the design pattern in Schneier's Applied Cryptography, using a secure hash algorithm, such as SHA1 or MD5 as a mixing and output primitive.

IMPORTANT: Please note that the generator design relies crucially on the presence of a proper amount and "quality" of seeding entropy (see below). Optional use of the `seed(byte[])` method with no arguments causes the generator to be seeded with 20 bytes of seeding material from `SpinnerEntropySource`.

It is presumed that users understand the crucial role that seeding entropy plays in the secure initialization of PRNGs. While it is not within the scope of the API documentation to explain how exactly PRNGs work, at the very least one would do well to observe that PRNGs do not "create" randomness so much as they "stretch" and "whiten" an initial pool of randomness. That is, a well-designed PRNG produces a uniform, uncorrelated output sequence, whose words are strongly non-computable from one iteration to the next. However, at their basic design level, they are still deterministic functions -- essentially (one-way) stream ciphers -- whose outputs are, (with some overhead) no more unguessable than their inputs. In this sense the starting value of a generator can be thought of as its "key", and should be strongly protected from eavesdropping or dictionary attacks.

Thus, seed values should never be transmitted in the clear, or stored in (non-secure) files; nor should they ever be re-used, and sources used to "generate" or gather seeding material should themselves be as non-deterministic as possible.

A few caveats about seeding:

- Currently recommended best practice is that PRNGs should use at least 128 to 160 bits of seeding material, preferably from a diverse range of sources. This means 16 to 20 bytes of entropy are needed. It is also recommended that generators be reseeded with new entropy from time to time (how frequently is a matter of debate).
- According to current recommendations (e.g. RFC 1750 or IEEE P1363), the best sources of scalable seeding entropy are dedicated hardware devices based on random physical processes (e.g., disk drive seek latency) or specially designed "entropy drivers" such as the Intel 810 RNG chipset.)
- Unfortunately, such devices (and reliable drivers for them) are not generally available on the vast majority of computing platforms. Until this situation improves, the next best thing commonly in use is to poll from a number of "very obscure" sources, such as hashes of running system properties, AWT events, one-time digests of user-supplied secrets, etc.

See Also:
  `EntropySource`, `SpinnerEntropySource`

Constructor Summary
`protected` | `DigestRandomBitsSource()`

Method Summary
`void` | `clear()` Clears (zeroes) the pool state of the PRNG, in effect bringing it to the same state as a newly-constructed, unseeded instance.
`protected void` | `initialize(AlgorithmIdentifier algID)` Initializes this `DigestRandomBitsSource`.
`byte` | `randomByte()` Returns the next output byte.
`byte[]` | `randomBytes(byte[] bytes)` Fills the supplied array with the requsite number of output bytes.
`void` | `seed()` Seeds this PRNG with 20 bytes of seeding material from the default entropy source.
`void` | `seed(byte[] b)` Seeds this random bits source with a given array of bytes.
`void` | `seed(EntropySource es)` Seeds this PRNG with 20 bytes of seeding material from the specified entropy source.
`void` | `seed(java.lang.Object o)` Seeds the PRNG with the output of the `hashCode` and `toString` methods of the current object.

Methods inherited from class oracle.security.crypto.core.RandomBitsSource
`getDefault, randomBigInteger, setDefault`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### DigestRandomBitsSource

    protected DigestRandomBitsSource()

Method Detail

### initialize

    protected void initialize(AlgorithmIdentifier algID)

  Initializes this `DigestRandomBitsSource`. Subclasses should call this method in their constructors.
  Parameters:
    `algID` - The algorithm identifier of the message digest to be used for this PRNG.
  See Also:
    `AlgID`, `MessageDigest`

### seed

    public void seed(byte[] b)

  Seeds this random bits source with a given array of bytes.
  Specified by:
    `seed` in class `RandomBitsSource`

### seed

    public void seed(java.lang.Object o)

  Seeds the PRNG with the output of the `hashCode` and `toString` methods of the current object. (The entropy available through such conversions is obviously quite variable, and should be estimated conservatively.)

### seed

    public void seed()

  Seeds this PRNG with 20 bytes of seeding material from the default entropy source.
  Overrides:
    `seed` in class `RandomBitsSource`
  See Also:
    `EntropySource`

### seed

    public void seed(EntropySource es)

  Seeds this PRNG with 20 bytes of seeding material from the specified entropy source.
  Specified by:
    `seed` in class `RandomBitsSource`
  See Also:
    `EntropySource`

### randomByte

    public byte randomByte()

  Returns the next output byte. (If the PRNG is in an unseeded state, a runtime exception will be thrown.)
  Specified by:
    `randomByte` in class `RandomBitsSource`

### randomBytes

    public byte[] randomBytes(byte[] bytes)

  Fills the supplied array with the requsite number of output bytes. (If the PRNG is in an unseeded state, an exception will be thrown.)
  Overrides:
    `randomBytes` in class `RandomBitsSource`

### clear

    public void clear()

  Clears (zeroes) the pool state of the PRNG, in effect bringing it to the same state as a newly-constructed, unseeded instance. Accordingly, the generator will be insecure in this state, and will refuse to return output bytes until it has been re-seeded.
  Specified by:
    `clear` in class `RandomBitsSource`

Overview | Package | Class | Tree | Deprecated | Index | Help
| Oracle Security Developer Tools Crypto Java API Reference 10g Release 3 (10.1.3) B25378-01
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2005, 2006 , Oracle. All rights reserved.