FileDocCategorySizeDatePackage
SecureRandom.javaAPI DocJava SE 5 API18625Fri Aug 26 14:57:16 BST 2005java.security

SecureRandom

public class SecureRandom extends Random

This class provides a cryptographically strong random number generator (RNG). Many 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.

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 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 RNG 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 random = SecureRandom.getInstance("SHA1PRNG");
random.setSeed(seed);

After the caller obtains the SecureRandom object from the getInstance call, it can call nextBytes to generate random bytes:

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

The caller 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);
see
java.security.SecureRandomSpi
see
java.util.Random
version
1.47, 12/19/03
author
Benjamin Renaud
author
Josh Bloch

Fields Summary
private Provider
provider
The provider.
private SecureRandomSpi
secureRandomSpi
The provider implementation.
private String
algorithm
private static SecureRandom
seedGenerator
static final long
serialVersionUID
private byte[]
state
private MessageDigest
digest
private byte[]
randomBytes
private int
randomBytesUsed
private long
counter
Constructors Summary
public 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.


                                                                                                       
      
	/*
	 * This call to our superclass constructor will result in a call
	 * to our own <code>setSeed</code> method, which will return
	 * immediately when it is passed zero.
	 */
	super(0);
	getDefaultPRNG(false, null);
    
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.

param
seed the seed.

	super(0);
	getDefaultPRNG(true, seed);
    
protected SecureRandom(SecureRandomSpi secureRandomSpi, Provider provider)
Creates a SecureRandom object.

param
secureRandomSpi the SecureRandom implementation.
param
provider the provider.

	this(secureRandomSpi, provider, null);
    
private SecureRandom(SecureRandomSpi secureRandomSpi, Provider provider, String algorithm)

	super(0);
	this.secureRandomSpi = secureRandomSpi;
	this.provider = provider;
	this.algorithm = algorithm;
    
Methods Summary
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.

param
numBytes the number of seed bytes to generate.
return
the seed bytes.

	return secureRandomSpi.engineGenerateSeed(numBytes);
    
public java.lang.StringgetAlgorithm()
Returns the name of the algorithm implemented by this SecureRandom object.

return
the name of the algorithm or unknown if the algorithm name cannot be determined.
since
1.5

	return (algorithm != null) ? algorithm : "unknown";
    
private voidgetDefaultPRNG(boolean setSeed, byte[] seed)

	String prng = getPrngAlgorithm();
	if (prng == null) {
	    // bummer, get the SUN implementation
	    prng = "SHA1PRNG";
	    this.secureRandomSpi = new sun.security.provider.SecureRandom();
	    this.provider = new sun.security.provider.Sun();
	    if (setSeed) {
		this.secureRandomSpi.engineSetSeed(seed);
	    }
	} else {
	    try {
		SecureRandom random = SecureRandom.getInstance(prng);
		this.secureRandomSpi = random.getSecureRandomSpi();
		this.provider = random.getProvider();
		if (setSeed) {
		    this.secureRandomSpi.engineSetSeed(seed);
		}
	    } catch (NoSuchAlgorithmException nsae) {
		// never happens, because we made sure the algorithm exists
	    }
	}
	// set algorithm if SecureRandom not subclassed (JDK 1.1 style)
	if (getClass() == SecureRandom.class) {
	    this.algorithm = prng;
	}
    
public static java.security.SecureRandomgetInstance(java.lang.String algorithm)
Generates a SecureRandom object that implements the specified Random Number Generator (RNG) algorithm. If the default provider package provides an implementation of the requested algorithm, an instance of SecureRandom containing that implementation is returned. If the algorithm 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.

param
algorithm the name of the RNG algorithm. See Appendix A in the Java Cryptography Architecture API Specification & Reference for information about standard RNG algorithm names.
return
the new SecureRandom object.
exception
NoSuchAlgorithmException if the RNG algorithm is not available in the caller's environment.
since
1.2

	Instance instance = GetInstance.getInstance("SecureRandom", 
	    SecureRandomSpi.class, algorithm);
	return new SecureRandom((SecureRandomSpi)instance.impl,
	    instance.provider, algorithm);
    
public static java.security.SecureRandomgetInstance(java.lang.String algorithm, java.lang.String provider)
Generates a SecureRandom object for the specified RNG algorithm, as supplied from the specified provider, if such a RNG 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.

param
algorithm the name of the RNG algorithm. See Appendix A in the Java Cryptography Architecture API Specification & Reference for information about standard RNG algorithm names.
param
provider the name of the provider.
return
the new SecureRandom object.
exception
NoSuchAlgorithmException if the requested RNG implementation is not available from the provider.
exception
NoSuchProviderException if the provider has not been configured.
exception
IllegalArgumentException if the provider name is null or empty.
see
Provider
since
1.2

	Instance instance = GetInstance.getInstance("SecureRandom", 
	    SecureRandomSpi.class, algorithm, provider);
	return new SecureRandom((SecureRandomSpi)instance.impl,
	    instance.provider, algorithm);
    
public static java.security.SecureRandomgetInstance(java.lang.String algorithm, java.security.Provider provider)
Generates a SecureRandom object for the specified RNG algorithm, as supplied from the specified provider, if such a RNG 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.

param
algorithm the name of the RNG algorithm. See Appendix A in the Java Cryptography Architecture API Specification & Reference for information about standard RNG algorithm names.
param
provider the provider.
return
the new SecureRandom object.
exception
NoSuchAlgorithmException if the requested RNG implementation is not available from the provider.
exception
IllegalArgumentException if the provider is null.
see
Provider
since
1.4

	Instance instance = GetInstance.getInstance("SecureRandom", 
	    SecureRandomSpi.class, algorithm, provider);
	return new SecureRandom((SecureRandomSpi)instance.impl,
	    instance.provider, algorithm);
    
private static java.lang.StringgetPrngAlgorithm()
Gets a default PRNG algorithm by looking through all registered providers. Returns the first PRNG algorithm of the first provider that has registered a SecureRandom implementation, or null if none of the registered providers supplies a SecureRandom implementation.

	List provs = Providers.getProviderList().providers();
	for (Iterator t = provs.iterator(); t.hasNext();) {
	    Provider p = (Provider)t.next();
	    for (Iterator u = p.getServices().iterator(); u.hasNext();) {
		Service s = (Service)u.next();
		if (s.getType().equals("SecureRandom")) {
		    return s.getAlgorithm();
		}
	    }
	}
	return null;
    
public final java.security.ProvidergetProvider()
Returns the provider of this SecureRandom object.

return
the provider of this SecureRandom object.

	return provider;
    
java.security.SecureRandomSpigetSecureRandomSpi()
Returns the SecureRandomSpi of this SecureRandom object.

	return secureRandomSpi;
    
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.

param
numBytes the number of seed bytes to generate.
return
the seed bytes.
see
#setSeed

	if (seedGenerator == null)
	    seedGenerator = new SecureRandom();
	return seedGenerator.generateSeed(numBytes);
    
private static byte[]longToByteArray(long l)
Helper function to convert a long into a byte array (least significant byte first).

	byte[] retVal = new byte[8];

	for (int i = 0; i < 8; i++) {
	    retVal[i] = (byte) l;
	    l >>= 8;
	}

	return retVal;
    
protected final intnext(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).

param
numBits number of pseudo-random bits to be generated, where 0 <= numBits <= 32.
return
an int containing the user-specified number of pseudo-random bits (right justified, with leading zeros).

	int numBytes = (numBits+7)/8;
	byte b[] = new byte[numBytes];
	int next = 0;
 
	nextBytes(b);
	for (int i = 0; i < numBytes; i++)
	    next = (next << 8) + (b[i] & 0xFF);
 
	return next >>> (numBytes*8 - numBits);
    
public synchronized voidnextBytes(byte[] bytes)
Generates a user-specified number of random bytes. This method is used as the basis of all random entities returned by this class (except seed bytes).

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

	secureRandomSpi.engineNextBytes(bytes);
    
public synchronized voidsetSeed(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.

param
seed the seed.
see
#getSeed

	secureRandomSpi.engineSetSeed(seed);
    
public voidsetSeed(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.

param
seed the seed.
see
#getSeed

	/* 
	 * Ignore call from super constructor (as well as any other calls
	 * unfortunate enough to be passing 0).  It's critical that we
	 * ignore call from superclass constructor, as digest has not
	 * yet been initialized at that point.
	 */
	if (seed != 0) {
	    secureRandomSpi.engineSetSeed(longToByteArray(seed));
	}