java.security

Class SecureRandom

java.lang.Object

java.util.Random

java.security.SecureRandom

All Implemented Interfaces:

java.io.Serializable

public class SecureRandom
extends java.util.Random

This class provides a cryptographically strong random number generator (RNG).

A cryptographically strong 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. Therefore any seed material passed to a SecureRandom object must be unpredictable, and all SecureRandom output sequences must be cryptographically strong, as described in RFC 1750: Randomness Recommendations for Security.

A caller obtains a SecureRandom instance via the no-argument constructor:

 SecureRandom random = new SecureRandom();
 

Many SecureRandom implementations are in the form of a pseudo-random number generator (PRNG), which means they use a deterministic algorithm to produce a pseudo-random sequence from a true random seed. Other implementations may produce true random numbers, and yet others may use a combination of both techniques.

Typical callers of SecureRandom invoke the following methods to retrieve random bytes:

 SecureRandom random = new SecureRandom();
 byte bytes[] = new byte[20];
 random.nextBytes(bytes);
 

Callers may also invoke the generateSeed method to generate a given number of seed bytes (to seed other random number generators, for example):

 byte seed[] = random.generateSeed(20);
 

Note: Depending on the implementation, the generateSeed and nextBytes methods may block as entropy is being gathered, for example, if they need to read from /dev/random on various Unix-like operating systems.

See Also:

Random, Serialized Form

Constructor Summary

Constructors

Constructor and Description
SecureRandom() Constructs a secure random number generator (RNG) implementing the default random number algorithm.
SecureRandom(byte[] seed) Constructs a secure random number generator (RNG) implementing the default random number algorithm.

Method Summary

Modifier and Type	Method and Description
byte[]	generateSeed(int numBytes) Returns the given number of seed bytes, computed using the seed generation algorithm that this class uses to seed itself.
protected int	next(int numBits) Generates an integer containing the user-specified number of pseudo-random bits (right justified, with leading zeros).
void	nextBytes(byte[] bytes) Generates a user-specified number of random bytes.
void	setSeed(byte[] seed) Reseeds this random object.
void	setSeed(long seed) Reseeds this random object, using the eight bytes contained in the given long seed.

Methods inherited from class java.util.Random

nextBoolean, nextDouble, nextFloat, nextGaussian, nextInt, nextInt, nextLong

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SecureRandom

public SecureRandom()

Constructs a secure random number generator (RNG) implementing the default random number algorithm.

The returned SecureRandom object has not been seeded. To seed the returned object, call the setSeed method. If setSeed is not called, the first call to nextBytes will force the SecureRandom object to seed itself. This self-seeding will not occur if setSeed was previously called.

SecureRandom

public SecureRandom(byte[] seed)

Constructs a secure random number generator (RNG) implementing the default random number algorithm. The SecureRandom instance is seeded with the specified seed bytes.

Parameters:

seed - the seed.

Method Detail

setSeed

public void setSeed(byte[] seed)

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

Parameters:

seed - the seed.

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.

This method is defined for compatibility with java.util.Random.

Overrides:

setSeed in class java.util.Random

Parameters:

seed - the seed.

nextBytes

public void nextBytes(byte[] bytes)

Generates a user-specified number of random bytes.

If a call to setSeed had not occurred previously, the first call to this method forces this SecureRandom object to seed itself. This self-seeding will not occur if setSeed was previously called.

Overrides:

nextBytes in class java.util.Random

Parameters:

bytes - the array to be filled in with random bytes.

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).

Overrides:

next in class java.util.Random

Parameters:

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).

generateSeed

public byte[] generateSeed(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.

Parameters:

numBytes - the number of seed bytes to generate.

Returns:

the seed bytes.