java.security
Class SecureRandom

This class provides a cryptographically strong pseudo-random number
generator (PRNG). A cryptographically strong pseudo-random number
minimally complies with the statistical random number generator tests
specified in FIPS 140-2, Security Requirements for Cryptographic Modules, section 4.9.1.
Additionally, SecureRandom must produce non-deterministic
output and therefore it is required that the seed material be unpredictable
and that output of SecureRandom be cryptographically strong sequences as
described in RFC 1750: Randomness Recommendations for Security.

Like other algorithm-based classes in Java Security, SecureRandom
provides implementation-independent algorithms, whereby a caller
(application code) requests a particular PRNG algorithm
and is handed back a SecureRandom object for that algorithm. It is
also possible, if desired, to request a particular algorithm from a
particular provider. See the getInstance methods.

Thus, there are two ways to request a SecureRandom object: by
specifying either just an algorithm name, or both an algorithm name
and a package provider.

If just an algorithm name is specified, as in:

SecureRandom random = SecureRandom.getInstance("SHA1PRNG");

the system will determine if there is an implementation of the algorithm
requested available in the environment, and if there is more than one, if
there is a preferred one.

If both an algorithm name and a package provider are specified, as in:

SecureRandom random = SecureRandom.getInstance("SHA1PRNG", "SUN");

the system will determine if there is an implementation of the
algorithm in the package requested, and throw an exception if there
is not.

The SecureRandom implementation attempts to completely
randomize the internal state of the generator itself unless
the caller follows the call to a getInstance method
with a call to the setSeed method:

SecureRandom()
By using this constructor, the caller obtains a SecureRandom object
containing the implementation from the highest-priority installed
provider that has a SecureRandom implementation.

SecureRandom(byte[] seed)
By using this constructor, the caller obtains a SecureRandom object
containing the implementation from the highest-priority installed
provider that has a SecureRandom implementation.

getInstance(String algorithm,
Provider provider)
Generates a SecureRandom object for the specified PRNG
algorithm, as supplied from the specified provider, if such a
PRNG implementation is available from the provider.

getInstance(String algorithm,
String provider)
Generates a SecureRandom object for the specified PRNG
algorithm, as supplied from the specified provider, if such a
PRNG implementation is available from the provider.

SecureRandom

By using this constructor, the caller obtains a SecureRandom object
containing the implementation from the highest-priority installed
provider that has a SecureRandom implementation.

Note that this instance of SecureRandom has not been seeded.
A call to the setSeed method will seed the SecureRandom
object. If a call is not made to setSeed, the first call
to the nextBytes method will force the SecureRandom object
to seed itself.

This constructor is provided for backwards compatibility.
The caller is encouraged to use one of the alternative
getInstance methods to obtain a SecureRandom object.

SecureRandom

public SecureRandom(byte[] seed)

By using this constructor, the caller obtains a SecureRandom object
containing the implementation from the highest-priority installed
provider that has a SecureRandom implementation. This constructor
uses a user-provided seed in
preference to the self-seeding algorithm referred to in the empty
constructor description. It may be preferable to the empty constructor
if the caller has access to high-quality random bytes from some physical
device (for example, a radiation detector or a noisy diode).

This constructor is provided for backwards compatibility.
The caller is encouraged to use one of the alternative
getInstance methods to obtain a SecureRandom object, and
then to call the setSeed method to seed it.

getInstance

Generates a SecureRandom object that implements the specified
Pseudo Random Number Generator (PRNG) algorithm. If the default
provider package provides an implementation of the requested PRNG,
an instance of SecureRandom containing that implementation is returned.
If the PRNG is not available in the default
package, other packages are searched.

Note that the returned instance of SecureRandom has not been seeded.
A call to the setSeed method will seed the SecureRandom
object. If a call is not made to setSeed, the first call
to the nextBytes method will force the SecureRandom object
to seed itself.

Parameters:

algorithm - the name of the PRNG algorithm.
See Appendix A in the
Java Cryptography Architecture API Specification & Reference
for information about standard PRNG algorithm names.

getInstance

Generates a SecureRandom object for the specified PRNG
algorithm, as supplied from the specified provider, if such a
PRNG implementation is available from the provider.

Note that the returned instance of SecureRandom has not been seeded.
A call to the setSeed method will seed the SecureRandom
object. If a call is not made to setSeed, the first call
to the nextBytes method will force the SecureRandom object
to seed itself.

Parameters:

algorithm - the name of the PRNG algorithm.
See Appendix A in the
Java Cryptography Architecture API Specification & Reference
for information about standard PRNG algorithm names.

getInstance

Generates a SecureRandom object for the specified PRNG
algorithm, as supplied from the specified provider, if such a
PRNG implementation is available from the provider.
Note: the provider doesn't have to be registered.

Note that the returned instance of SecureRandom has not been seeded.
A call to the setSeed method will seed the SecureRandom
object. If a call is not made to setSeed, the first call
to the nextBytes method will force the SecureRandom object
to seed itself.

Parameters:

algorithm - the name of the PRNG algorithm.
See Appendix A in the
Java Cryptography Architecture API Specification & Reference
for information about standard PRNG algorithm names.

setSeed

public void setSeed(long seed)

Reseeds this random object, using the eight bytes contained
in the given long seed. The given seed supplements,
rather than replaces, the existing seed. Thus, repeated calls
are guaranteed never to reduce randomness.

next

protected final int next(int numBits)

Generates an integer containing the user-specified number of
pseudo-random bits (right justified, with leading zeros). This
method overrides a java.util.Random method, and serves
to provide a source of random bits to all of the methods inherited
from that class (for example, nextInt,
nextLong, and nextFloat).

numBits - number of pseudo-random bits to be generated, where
0 <= numBits <= 32.

Returns:

an int containing the user-specified number
of pseudo-random bits (right justified, with leading zeros).

getSeed

public static byte[] getSeed(int numBytes)

Returns the given number of seed bytes, computed using the seed
generation algorithm that this class uses to seed itself. This
call may be used to seed other random number generators.

This method is only included for backwards compatibility.
The caller is encouraged to use one of the alternative
getInstance methods to obtain a SecureRandom object, and
then call the generateSeed method to obtain seed bytes
from that object.

A script enabled browser is required for this page to function properly.A script enabled browser is required for this page to function properly.A script enabled browser is required for this page to function properly.A script enabled browser is required for this page to function properly.A script enabled browser is required for this page to function properly.