java.security

Class SecureRandom

java.lang.Object

java.util.Random

java.security.SecureRandom

All Implemented Interfaces:

Serializable

public class SecureRandom
extends Random

This class generates cryptographically secure pseudo-random numbers. It is best to invoke SecureRandom using the default constructor. This will provide an instance of the most cryptographically strong provider available:

SecureRandom sr = new SecureRandom();
 byte[] output = new byte[16];
 sr.nextBytes(output);

The default algorithm is defined by the first SecureRandomSpi provider found in the installed security providers. Use Security to install custom SecureRandomSpi providers.

Note that the output of a SecureRandom instance should never be relied upon to be deterministic. For deterministic output from a given input, see MessageDigest which provides one-way hash functions. For deriving keys from passwords, see SecretKeyFactory.

Seeding SecureRandom may be insecure

A seed is an array of bytes used to bootstrap random number generation. To produce cryptographically secure random numbers, both the seed and the algorithm must be secure.

By default, instances of this class will generate an initial seed using an internal entropy source, such as /dev/urandom. This seed is unpredictable and appropriate for secure use.

Using the seeded constructor or calling setSeed(byte[]) may completely replace the cryptographically strong default seed causing the instance to return a predictable sequence of numbers unfit for secure use. Due to variations between implementations it is not recommended to use setSeed at all.

See Also:

Serialized Form

Constructor Summary

Constructors

Modifier	Constructor and Description
	SecureRandom() Constructs a new SecureRandom that uses the default algorithm.
	SecureRandom(byte[] seed) Constructs a new seeded SecureRandom that uses the default algorithm.
protected	SecureRandom(SecureRandomSpi secureRandomSpi, Provider provider) Constructs a new instance of SecureRandom using the given implementation from the specified provider.

Method Summary

Modifier and Type	Method and Description
byte[]	generateSeed(int numBytes) Generates and returns the specified number of seed bytes, computed using the seed generation algorithm used by this SecureRandom.
String	getAlgorithm() Returns the name of the algorithm of this SecureRandom.
static SecureRandom	getInstance(String algorithm) Returns a new instance of SecureRandom that utilizes the specified algorithm.
static SecureRandom	getInstance(String algorithm, Provider provider) Returns a new instance of SecureRandom that utilizes the specified algorithm from the specified provider.
static SecureRandom	getInstance(String algorithm, String provider) Returns a new instance of SecureRandom that utilizes the specified algorithm from the specified provider.
Provider	getProvider() Returns the provider associated with this SecureRandom.
static byte[]	getSeed(int numBytes) Generates and returns the specified number of seed bytes, computed using the seed generation algorithm used by this SecureRandom.
protected int	next(int numBits) Generates and returns an int containing the specified number of random bits (right justified, with leading zeros).
void	nextBytes(byte[] bytes) Generates and stores random bytes in the given byte[] for each array element.
void	setSeed(byte[] seed) Seeds this SecureRandom instance with the specified seed.
void	setSeed(long seed) Seeds this SecureRandom instance with the specified eight-byte seed.

Methods inherited from class java.util.Random

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

Methods inherited from class java.lang.Object

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

Constructor Detail

SecureRandom

public SecureRandom()

Constructs a new SecureRandom that uses the default algorithm.

SecureRandom

public SecureRandom(byte[] seed)

Constructs a new seeded SecureRandom that uses the default algorithm. Seeding SecureRandom may be insecure.

SecureRandom

protected SecureRandom(SecureRandomSpi secureRandomSpi,
                       Provider provider)

Constructs a new instance of SecureRandom using the given implementation from the specified provider.

Parameters:

secureRandomSpi - the implementation.

provider - the security provider.

Method Detail

getInstance

public static SecureRandom getInstance(String algorithm)
                                throws NoSuchAlgorithmException

Returns a new instance of SecureRandom that utilizes the specified algorithm.

Parameters:

algorithm - the name of the algorithm to use.

Returns:

a new instance of SecureRandom that utilizes the specified algorithm.

Throws:

NoSuchAlgorithmException - if the specified algorithm is not available.

NullPointerException - if algorithm is null.

getInstance

public static SecureRandom getInstance(String algorithm,
                                       String provider)
                                throws NoSuchAlgorithmException,
                                       NoSuchProviderException

Returns a new instance of SecureRandom that utilizes the specified algorithm from the specified provider.

Parameters:

algorithm - the name of the algorithm to use.

provider - the name of the provider.

Returns:

a new instance of SecureRandom that utilizes the specified algorithm from the specified provider.

Throws:

NoSuchAlgorithmException - if the specified algorithm is not available.

NoSuchProviderException - if the specified provider is not available.

NullPointerException - if algorithm is null.

IllegalArgumentException - if provider == null || provider.isEmpty()

getInstance

public static SecureRandom getInstance(String algorithm,
                                       Provider provider)
                                throws NoSuchAlgorithmException

Returns a new instance of SecureRandom that utilizes the specified algorithm from the specified provider. The provider supplied does not have to be registered.

Parameters:

algorithm - the name of the algorithm to use.

provider - the security provider.

Returns:

a new instance of SecureRandom that utilizes the specified algorithm from the specified provider.

Throws:

NoSuchAlgorithmException - if the specified algorithm is not available.

NullPointerException - if algorithm is null.

IllegalArgumentException - if provider == null

getProvider

public final Provider getProvider()

Returns the provider associated with this SecureRandom.

Returns:

the provider associated with this SecureRandom.

getAlgorithm

public String getAlgorithm()

Returns the name of the algorithm of this SecureRandom.

Returns:

the name of the algorithm of this SecureRandom.

setSeed

public void setSeed(byte[] seed)

Seeds this SecureRandom instance with the specified seed. Seeding SecureRandom may be insecure.

setSeed

public void setSeed(long seed)

Seeds this SecureRandom instance with the specified eight-byte seed. Seeding SecureRandom may be insecure.

Overrides:

setSeed in class Random

nextBytes

public void nextBytes(byte[] bytes)

Generates and stores random bytes in the given byte[] for each array element.

Overrides:

nextBytes in class Random

Parameters:

bytes - the byte[] to be filled with random bytes.

next

protected final int next(int numBits)

Generates and returns an int containing the specified number of random bits (right justified, with leading zeros).

Overrides:

next in class Random

Parameters:

numBits - number of bits to be generated. An input value should be in the range [0, 32].

Returns:

an int containing the specified number of random bits.

getSeed

public static byte[] getSeed(int numBytes)

Generates and returns the specified number of seed bytes, computed using the seed generation algorithm used by this SecureRandom.

Parameters:

numBytes - the number of seed bytes.

Returns:

the seed bytes

generateSeed

public byte[] generateSeed(int numBytes)

Generates and returns the specified number of seed bytes, computed using the seed generation algorithm used by this SecureRandom.

Parameters:

numBytes - the number of seed bytes.

Returns:

the seed bytes.