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 or one of the getInstance methods:
*
*
* 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.
*
* The SHA1PRNG algorithm from the Crypto provider has been deprecated as it was insecure, and also
* incorrectly used by some apps as a key derivation function. See
*
* Security "Crypto" provider deprecated in Android N for details.
*
* @see java.security.SecureRandomSpi
* @see java.util.Random
*
* @author Benjamin Renaud
* @author Josh Bloch
*/
public class SecureRandom extends java.util.Random {
/**
* The provider.
*
* @serial
* @since 1.2
*/
private Provider provider = null;
/**
* The provider implementation.
*
* @serial
* @since 1.2
*/
private SecureRandomSpi secureRandomSpi = null;
/*
* The algorithm name of null if unknown.
*
* @serial
* @since 1.5
*/
private String algorithm;
// Seed Generator
private static volatile SecureRandom seedGenerator = null;
/**
* Constructs a secure random number generator (RNG) implementing the
* default random number algorithm.
*
* This constructor traverses the list of registered security Providers, * starting with the most preferred Provider. * A new SecureRandom object encapsulating the * SecureRandomSpi implementation from the first * Provider that supports a SecureRandom (RNG) algorithm is returned. * If none of the Providers support a RNG algorithm, * then an implementation-specific default is returned. * *
Note that the list of registered providers may be retrieved via * the {@link Security#getProviders() Security.getProviders()} method. * *
See the SecureRandom section in the * Java Cryptography Architecture Standard Algorithm Name Documentation * for information about standard RNG algorithm names. * *
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.
*/
public SecureRandom() {
/*
* This call to our superclass constructor will result in a call
* to our own setSeed method, which will return
* immediately when it is passed zero.
*/
super(0);
getDefaultPRNG(false, null);
}
/**
* Constructs a secure random number generator (RNG) implementing the
* default random number algorithm.
* The SecureRandom instance is seeded with the specified seed bytes.
*
*
This constructor traverses the list of registered security Providers, * starting with the most preferred Provider. * A new SecureRandom object encapsulating the * SecureRandomSpi implementation from the first * Provider that supports a SecureRandom (RNG) algorithm is returned. * If none of the Providers support a RNG algorithm, * then an implementation-specific default is returned. * *
Note that the list of registered providers may be retrieved via * the {@link Security#getProviders() Security.getProviders()} method. * *
See the SecureRandom section in the * Java Cryptography Architecture Standard Algorithm Name Documentation * for information about standard RNG algorithm names. * * @param seed the seed. */ public SecureRandom(byte seed[]) { super(0); getDefaultPRNG(true, seed); } private void getDefaultPRNG(boolean setSeed, byte[] seed) { String prng = getPrngAlgorithm(); if (prng == null) { // Android changed, should never happen throw new IllegalStateException("No SecureRandom implementation!"); } 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 throw new RuntimeException(nsae); } } // JDK 1.1 based implementations subclass SecureRandom instead of // SecureRandomSpi. They will also go through this code path because // they must call a SecureRandom constructor as it is their superclass. // If we are dealing with such an implementation, do not set the // algorithm value as it would be inaccurate. if (getClass() == SecureRandom.class) { this.algorithm = prng; } } /** * Creates a SecureRandom object. * * @param secureRandomSpi the SecureRandom implementation. * @param provider the provider. */ protected SecureRandom(SecureRandomSpi secureRandomSpi, Provider provider) { this(secureRandomSpi, provider, null); } private SecureRandom(SecureRandomSpi secureRandomSpi, Provider provider, String algorithm) { super(0); this.secureRandomSpi = secureRandomSpi; this.provider = provider; this.algorithm = algorithm; } /** * Returns a SecureRandom object that implements the specified * Random Number Generator (RNG) algorithm. * *
This method traverses the list of registered security Providers, * starting with the most preferred Provider. * A new SecureRandom object encapsulating the * SecureRandomSpi implementation from the first * Provider that supports the specified algorithm is returned. * *
Note that the list of registered providers may be retrieved via * the {@link Security#getProviders() Security.getProviders()} method. * *
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.
*
* @param algorithm the name of the RNG algorithm.
* See the SecureRandom section in the
* Java Cryptography Architecture Standard Algorithm Name Documentation
* for information about standard RNG algorithm names.
*
* @return the new SecureRandom object.
*
* @exception NoSuchAlgorithmException if no Provider supports a
* SecureRandomSpi implementation for the
* specified algorithm.
*
* @see Provider
*
* @since 1.2
*/
public static SecureRandom getInstance(String algorithm)
throws NoSuchAlgorithmException {
Instance instance = GetInstance.getInstance("SecureRandom",
SecureRandomSpi.class, algorithm);
return new SecureRandom((SecureRandomSpi)instance.impl,
instance.provider, algorithm);
}
/**
* Maximum SDK version for which the workaround for the Crypto provider is in place.
*
*
We provide instances from the Crypto provider (although the provider is not installed) to * apps targeting M or earlier versions of the SDK. * *
Default is 23 (M). We have it as a field for testability and it shouldn't be changed. * * @hide */ public static final int DEFAULT_SDK_TARGET_FOR_CRYPTO_PROVIDER_WORKAROUND = 23; private static int sdkTargetForCryptoProviderWorkaround = DEFAULT_SDK_TARGET_FOR_CRYPTO_PROVIDER_WORKAROUND; /** * Only for testing. * * @hide */ public static void setSdkTargetForCryptoProviderWorkaround(int sdkTargetVersion) { sdkTargetForCryptoProviderWorkaround = sdkTargetVersion; } /** * Only for testing. * * @hide */ public static int getSdkTargetForCryptoProviderWorkaround() { return sdkTargetForCryptoProviderWorkaround; } /** * Returns a SecureRandom object that implements the specified * Random Number Generator (RNG) algorithm. * *
A new SecureRandom object encapsulating the * SecureRandomSpi implementation from the specified provider * is returned. The specified provider must be registered * in the security provider list. * *
Note that the list of registered providers may be retrieved via * the {@link Security#getProviders() Security.getProviders()} method. * *
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.
*
* @param algorithm the name of the RNG algorithm.
* See the SecureRandom section in the
* Java Cryptography Architecture Standard Algorithm Name Documentation
* for information about standard RNG algorithm names.
*
* @param provider the name of the provider.
*
* @return the new SecureRandom object.
*
* @exception NoSuchAlgorithmException if a SecureRandomSpi
* implementation for the specified algorithm is not
* available from the specified provider.
*
* @exception NoSuchProviderException if the specified provider is not
* registered in the security provider list.
*
* @exception IllegalArgumentException if the provider name is null
* or empty.
*
* @see Provider
*
* @since 1.2
*/
public static SecureRandom getInstance(String algorithm, String provider)
throws NoSuchAlgorithmException, NoSuchProviderException {
try {
Instance instance = GetInstance.getInstance("SecureRandom",
SecureRandomSpi.class, algorithm, provider);
return new SecureRandom((SecureRandomSpi) instance.impl,
instance.provider, algorithm);
} catch (NoSuchProviderException nspe) {
if ("Crypto".equals(provider)) {
System.logE(" ********** PLEASE READ ************ ");
System.logE(" * ");
System.logE(" * New versions of the Android SDK no longer support the Crypto provider.");
System.logE(" * If your app was relying on setSeed() to derive keys from strings, you");
System.logE(" * should switch to using SecretKeySpec to load raw key bytes directly OR");
System.logE(" * use a real key derivation function (KDF). See advice here : ");
System.logE(" * http://android-developers.blogspot.com/2016/06/security-crypto-provider-deprecated-in.html ");
System.logE(" *********************************** ");
if (VMRuntime.getRuntime().getTargetSdkVersion()
<= sdkTargetForCryptoProviderWorkaround) {
System.logE(" Returning an instance of SecureRandom from the Crypto provider");
System.logE(" as a temporary measure so that the apps targeting earlier SDKs");
System.logE(" keep working. Please do not rely on the presence of the Crypto");
System.logE(" provider in the codebase, as our plan is to delete it");
System.logE(" completely in the future.");
return getInstanceFromCryptoProvider(algorithm);
}
}
throw nspe;
}
}
private static SecureRandom getInstanceFromCryptoProvider(String algorithm)
throws NoSuchAlgorithmException {
Provider cryptoProvider;
try {
cryptoProvider = (Provider) SecureRandom.class.getClassLoader()
.loadClass(
"org.apache.harmony.security.provider.crypto.CryptoProvider")
.newInstance();
} catch (Exception e) {
throw new RuntimeException(e);
}
Service service = cryptoProvider.getService("SecureRandom", algorithm);
Instance instance = GetInstance.getInstance(service, SecureRandomSpi.class);
return new SecureRandom(
(SecureRandomSpi) instance.impl, instance.provider, algorithm);
}
/**
* Returns a SecureRandom object that implements the specified
* Random Number Generator (RNG) algorithm.
*
*
A new SecureRandom object encapsulating the * SecureRandomSpi implementation from the specified Provider * object is returned. Note that the specified Provider object * does not have to be registered in the provider list. * *
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.
*
* @param algorithm the name of the RNG algorithm.
* See the SecureRandom section in the
* Java Cryptography Architecture Standard Algorithm Name Documentation
* for information about standard RNG algorithm names.
*
* @param provider the provider.
*
* @return the new SecureRandom object.
*
* @exception NoSuchAlgorithmException if a SecureRandomSpi
* implementation for the specified algorithm is not available
* from the specified Provider object.
*
* @exception IllegalArgumentException if the specified provider is null.
*
* @see Provider
*
* @since 1.4
*/
public static SecureRandom getInstance(String algorithm,
Provider provider) throws NoSuchAlgorithmException {
Instance instance = GetInstance.getInstance("SecureRandom",
SecureRandomSpi.class, algorithm, provider);
return new SecureRandom((SecureRandomSpi)instance.impl,
instance.provider, algorithm);
}
/**
* Returns the SecureRandomSpi of this SecureRandom object.
*/
SecureRandomSpi getSecureRandomSpi() {
return secureRandomSpi;
}
/**
* Returns the provider of this SecureRandom object.
*
* @return the provider of this SecureRandom object.
*/
public final Provider getProvider() {
return provider;
}
/**
* 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
*/
public String getAlgorithm() {
return (algorithm != null) ? algorithm : "unknown";
}
/**
* 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
*/
synchronized public void setSeed(byte[] seed) {
secureRandomSpi.engineSetSeed(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
*/
public void setSeed(long seed) {
/*
* 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));
}
}
/**
* 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.
*
* @param bytes the array to be filled in with random bytes.
*/
synchronized public void nextBytes(byte[] bytes) {
secureRandomSpi.engineNextBytes(bytes);
}
/**
* 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).
*/
final protected int next(int numBits) {
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);
}
/**
* 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
*/
public static byte[] getSeed(int numBytes) {
if (seedGenerator == null)
seedGenerator = new SecureRandom();
return seedGenerator.generateSeed(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.
*/
public byte[] generateSeed(int numBytes) {
return secureRandomSpi.engineGenerateSeed(numBytes);
}
/**
* Helper function to convert a long into a byte array (least significant
* byte first).
*/
private static byte[] longToByteArray(long l) {
byte[] retVal = new byte[8];
for (int i = 0; i < 8; i++) {
retVal[i] = (byte) l;
l >>= 8;
}
return retVal;
}
/**
* 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.
*/
private static String getPrngAlgorithm() {
for (Provider p : Providers.getProviderList().providers()) {
for (Service s : p.getServices()) {
if (s.getType().equals("SecureRandom")) {
return s.getAlgorithm();
}
}
}
return null;
}
// Declare serialVersionUID to be compatible with JDK1.1
static final long serialVersionUID = 4940670005562187L;
// Retain unused values serialized from JDK1.1
/**
* @serial
*/
private byte[] state;
/**
* @serial
*/
private MessageDigest digest = null;
/**
* @serial
*
* We know that the MessageDigest class does not implement
* java.io.Serializable. However, since this field is no longer
* used, it will always be NULL and won't affect the serialization
* of the SecureRandom class itself.
*/
private byte[] randomBytes;
/**
* @serial
*/
private int randomBytesUsed;
/**
* @serial
*/
private long counter;
}