OpenJDK 1.22 · java.security.SecureRandom · APIdia, the JavaDoc alternative

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 4086: Randomness Requirements for Security.

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

A caller obtains a SecureRandom instance via the no-argument constructor or one of the getInstance methods. For example:

SecureRandom r1 = new SecureRandom();
SecureRandom r2 = SecureRandom.getInstance("NativePRNG");
SecureRandom r3 = SecureRandom.getInstance("DRBG",
        DrbgParameters.instantiation(128, RESEED_ONLY, null));

The third statement above returns a SecureRandom object of the specific algorithm supporting the specific instantiate parameters. The implementation's effective instantiated parameters must match this minimum request but is not necessarily the same. For example, even if the request does not require a certain feature, the actual instantiation can provide the feature. An implementation may lazily instantiate a SecureRandom until it's actually used, but the effective instantiate parameters must be determined right after it's created and getParameters() should always return the same result unchanged.

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

A newly created PRNG SecureRandom object is not seeded (except if it is created by SecureRandom(byte[])). The first call to nextBytes will force it to seed itself from an implementation- specific entropy source. This self-seeding will not occur if setSeed was previously called.

A SecureRandom can be reseeded at any time by calling the reseed or setSeed method. The reseed method reads entropy input from its entropy source to reseed itself. The setSeed method requires the caller to provide the seed.

Please note that reseed may not be supported by all SecureRandom implementations.

Some SecureRandom implementations may accept a SecureRandomParameters parameter in its nextBytes(byte[], SecureRandomParameters) and reseed(SecureRandomParameters) methods to further control the behavior of the methods.

Note

Depending on the implementation, the generateSeed, reseed and nextBytes methods may block as entropy is being gathered, for example, if the entropy source is /dev/random on various Unix-like operating systems.

Thread safety

SecureRandom objects are safe for use by multiple concurrent threads.

Nested and Inner Type Summary

Modifier and Type	Class and Description
private static class	SecureRandom.StrongPatternHolder

Field Summary

Modifier and Type	Field and Description
private String	algorithm The algorithm name or `null` if unknown.
private long	counter
private MessageDigest	digest
private static final Debug	pdebug
private Provider	provider The provider.
private byte[]	randomBytes
private int	randomBytesUsed
private SecureRandomSpi	secureRandomSpi The provider implementation.
private static volatile SecureRandom	seedGenerator
pack-priv static final long	serialVersionUID Hides java.util.Random.serialVersionUID.
private static final boolean	skipDebug
private byte[]	state
private final boolean	threadSafe Thread safety.

Constructor Summary

Access	Constructor and Description
public	SecureRandom() Constructs a secure random number generator (RNG) implementing the default random number algorithm.
public	SecureRandom(byte[] the seed. seed) Constructs a secure random number generator (RNG) implementing the default random number algorithm.
protected	SecureRandom(SecureRandomSpi the `SecureRandom` implementation. secureRandomSpi, Provider the provider. provider) Creates a `SecureRandom` object.
private	SecureRandom(SecureRandomSpi secureRandomSpi, Provider provider, String algorithm)

Method Summary

Modifier and Type	Method and Description
public byte[]	Returns: the seed bytes. generateSeed(int the number of seed bytes to generate. numBytes) Returns the given number of seed bytes, computed using the seed generation algorithm that this class uses to seed itself.
public String	Returns: the name of the algorithm or `unknown` if the algorithm name cannot be determined. getAlgorithm() Returns the name of the algorithm implemented by this `SecureRandom` object.
private void	getDefaultPRNG(boolean setSeed, byte[] seed)
public static SecureRandom	Returns: the new `SecureRandom` object getInstance(String the name of the RNG algorithm. See the `SecureRandom` section in the Java Security Standard Algorithm Names Specification for information about standard RNG algorithm names. algorithm) Returns a `SecureRandom` object that implements the specified Random Number Generator (RNG) algorithm.
public static SecureRandom	Returns: the new `SecureRandom` object getInstance(String the name of the RNG algorithm. See the `SecureRandom` section in the Java Security Standard Algorithm Names Specification for information about standard RNG algorithm names. algorithm, String the name of the provider. provider) Returns a `SecureRandom` object that implements the specified Random Number Generator (RNG) algorithm.
public static SecureRandom	Returns: the new `SecureRandom` object getInstance(String the name of the RNG algorithm. See the `SecureRandom` section in the Java Security Standard Algorithm Names Specification for information about standard RNG algorithm names. algorithm, Provider the provider. provider) Returns a `SecureRandom` object that implements the specified Random Number Generator (RNG) algorithm.
public static SecureRandom	Returns: the new `SecureRandom` object getInstance(String the name of the RNG algorithm. See the `SecureRandom` section in the Java Security Standard Algorithm Names Specification for information about standard RNG algorithm names. algorithm, SecureRandomParameters the `SecureRandomParameters` the newly created `SecureRandom` object must support. params) Returns a `SecureRandom` object that implements the specified Random Number Generator (RNG) algorithm and supports the specified `SecureRandomParameters` request.
public static SecureRandom	Returns: the new `SecureRandom` object getInstance(String the name of the RNG algorithm. See the `SecureRandom` section in the Java Security Standard Algorithm Names Specification for information about standard RNG algorithm names. algorithm, SecureRandomParameters the `SecureRandomParameters` the newly created `SecureRandom` object must support. params, String the name of the provider. provider) Returns a `SecureRandom` object that implements the specified Random Number Generator (RNG) algorithm and supports the specified `SecureRandomParameters` request.
public static SecureRandom	Returns: the new `SecureRandom` object getInstance(String the name of the RNG algorithm. See the `SecureRandom` section in the Java Security Standard Algorithm Names Specification for information about standard RNG algorithm names. algorithm, SecureRandomParameters the `SecureRandomParameters` the newly created `SecureRandom` object must support. params, Provider the provider. provider) Returns a `SecureRandom` object that implements the specified Random Number Generator (RNG) algorithm and supports the specified `SecureRandomParameters` request.
public static SecureRandom	Returns: a strong `SecureRandom` implementation as indicated by the `securerandom.strongAlgorithms` Security property getInstanceStrong() Returns a `SecureRandom` object that was selected by using the algorithms/providers specified in the `securerandom.strongAlgorithms` `Security` property.
public SecureRandomParameters	Returns: the effective `SecureRandomParameters` parameters, or `null` if no parameters were used. getParameters() Returns the effective `SecureRandomParameters` for this `SecureRandom` instance.
public final Provider	Returns: the provider of this `SecureRandom` object. getProvider() Returns the provider of this `SecureRandom` object.
private String	getProviderName()
public static byte[]	Returns: the seed bytes. getSeed(int the number of seed bytes to generate. numBytes) Returns the given number of seed bytes, computed using the seed generation algorithm that this class uses to seed itself.
private boolean	getThreadSafe()
private static byte[]	longToByteArray(long l) Helper function to convert a long into a byte array (least significant byte first).
protected final int	Returns: an `int` containing the user-specified number of pseudo-random bits (right justified, with leading zeros). next(int number of pseudo-random bits to be generated, where `0 <= numBits <= 32`. numBits) Overrides java.util.Random.next. Generates an integer containing the user-specified number of pseudo-random bits (right justified, with leading zeros).
public void	nextBytes(byte[] the array to be filled in with random bytes. bytes) Overrides java.util.Random.nextBytes. Overrides default java.util.random.RandomGenerator.nextBytes. Generates a user-specified number of random bytes.
public void	nextBytes(byte[] the array to be filled in with random bytes bytes, SecureRandomParameters additional parameters params) Generates a user-specified number of random bytes with additional parameters.
public void	reseed() Reseeds this `SecureRandom` with entropy input read from its entropy source.
public void	reseed(SecureRandomParameters extra parameters params) Reseeds this `SecureRandom` with entropy input read from its entropy source with additional parameters.
public void	setSeed(byte[] the seed. seed) Reseeds this random object with the given seed.
public void	setSeed(long the seed. seed) Overrides java.util.Random.setSeed. Reseeds this random object, using the eight bytes contained in the given `long seed`.
public String	Returns: the string representation toString() Overrides java.lang.Object.toString. Returns a Human-readable string representation of this `SecureRandom`.

Inherited from java.util.Random:: doubles doubles doubles doubles from ints ints ints ints longs longs longs longs nextBoolean nextDouble nextFloat nextGaussian nextInt nextInt nextLong

Field Detail

algorithm back to summary

algorithm	back to summary
private String algorithm The algorithm name or `null` if unknown. Since 1.5

private String algorithm

The algorithm name or null if unknown.

Since: 1.5

counter	back to summary
private long counter

digest	back to summary
private MessageDigest digest Annotations @SuppressWarnings:serial

pdebug	back to summary
private static final Debug pdebug

provider	back to summary
private Provider provider The provider. Since 1.2

provider

back to summary

private Provider provider

The provider.

Since: 1.2

randomBytes	back to summary
private byte[] randomBytes

randomBytesUsed	back to summary
private int randomBytesUsed

secureRandomSpi	back to summary
private SecureRandomSpi secureRandomSpi The provider implementation. Since 1.2

secureRandomSpi

back to summary

private SecureRandomSpi secureRandomSpi

The provider implementation.

Since: 1.2

seedGenerator	back to summary
private static volatile SecureRandom seedGenerator

serialVersionUID	back to summary
pack-priv static final long serialVersionUID Hides java.util.Random.serialVersionUID. Annotations @Serial

skipDebug	back to summary
private static final boolean skipDebug

state	back to summary
private byte[] state

threadSafe	back to summary
private final boolean threadSafe Thread safety. Since 9

threadSafe

back to summary

private final boolean threadSafe

Thread safety.

Since: 9

Constructor Detail

SecureRandom back to summary

SecureRandom	back to summary
public SecureRandom() 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 an RNG algorithm, then an implementation-specific default is returned. Note that the list of registered providers may be retrieved via the `Security.getProviders()` method. See the `SecureRandom` section in the Java Security Standard Algorithm Names Specification for information about standard RNG algorithm names.

public SecureRandom()

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 an RNG algorithm, then an implementation-specific default is returned.

Note that the list of registered providers may be retrieved via the Security.getProviders() method.

See the SecureRandom section in the Java Security Standard Algorithm Names Specification for information about standard RNG algorithm names.

SecureRandom back to summary

SecureRandom	back to summary
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. 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 an RNG algorithm, then an implementation-specific default is returned. Note that the list of registered providers may be retrieved via the `Security.getProviders()` method. See the `SecureRandom` section in the Java Security Standard Algorithm Names Specification for information about standard RNG algorithm names. Parameters seed:byte[] the seed. Exceptions NullPointerException: if `seed` is `null`

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.

Note that the list of registered providers may be retrieved via the Security.getProviders() method.

See the SecureRandom section in the Java Security Standard Algorithm Names Specification for information about standard RNG algorithm names.

Parameters

seed:byte[]: the seed.

Exceptions

NullPointerException:: if seed is null

SecureRandom back to summary

SecureRandom	back to summary
protected SecureRandom(SecureRandomSpi secureRandomSpi, Provider provider) Creates a `SecureRandom` object. Parameters secureRandomSpi:SecureRandomSpi the `SecureRandom` implementation. provider:Provider the provider.

protected SecureRandom(SecureRandomSpi secureRandomSpi, Provider provider)

Creates a SecureRandom object.

Parameters

secureRandomSpi:SecureRandomSpi: the SecureRandom implementation.
provider:Provider: the provider.

SecureRandom	back to summary
private SecureRandom(SecureRandomSpi secureRandomSpi, Provider provider, String algorithm)

Method Detail

generateSeed back to summary

generateSeed	back to 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. Parameters numBytes:int the number of seed bytes to generate. Returns:byte[] the seed bytes. Exceptions IllegalArgumentException: if `numBytes` is negative

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:int: the number of seed bytes to generate.

Returns:byte[]

the seed bytes.

Exceptions

IllegalArgumentException:: if numBytes is negative

getAlgorithm back to summary

getAlgorithm	back to summary
public String getAlgorithm() Returns the name of the algorithm implemented by this `SecureRandom` object. Returns:String the name of the algorithm or `unknown` if the algorithm name cannot be determined. Since 1.5

public String getAlgorithm()

Returns the name of the algorithm implemented by this SecureRandom object.

Returns:String: the name of the algorithm or unknown if the algorithm name cannot be determined.
Since: 1.5

getDefaultPRNG	back to summary
private void getDefaultPRNG(boolean setSeed, byte[] seed)

getInstance back to summary

getInstance	back to summary
public static SecureRandom getInstance(String algorithm) throws NoSuchAlgorithmException 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 `Security.getProviders()` method. Implementation Note The JDK Reference Implementation additionally uses the `jdk.security.provider.preferred` `Security` property to determine the preferred provider order for the specified algorithm. This may be different from the order of providers returned by `Security.getProviders()`. Parameters algorithm:String the name of the RNG algorithm. See the `SecureRandom` section in the Java Security Standard Algorithm Names Specification for information about standard RNG algorithm names. Returns:SecureRandom the new `SecureRandom` object Exceptions NoSuchAlgorithmException: if no `Provider` supports a `SecureRandomSpi` implementation for the specified algorithm NullPointerException: if `algorithm` is `null` Since 1.2 See Also `Provider`

public static SecureRandom getInstance(String algorithm) throws NoSuchAlgorithmException

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 Security.getProviders() method.

Implementation Note

The JDK Reference Implementation additionally uses the jdk.security.provider.preferred Security property to determine the preferred provider order for the specified algorithm. This may be different from the order of providers returned by Security.getProviders().

Parameters

algorithm:String: the name of the RNG algorithm. See the SecureRandom section in the Java Security Standard Algorithm Names Specification for information about standard RNG algorithm names.

Returns:SecureRandom

the new SecureRandom object

Exceptions

NoSuchAlgorithmException:: if no Provider supports a SecureRandomSpi implementation for the specified algorithm
NullPointerException:: if algorithm is null

Since

1.2

See Also

Provider

getInstance back to summary

getInstance	back to summary
public static SecureRandom getInstance(String algorithm, String provider) throws NoSuchAlgorithmException, NoSuchProviderException 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 `Security.getProviders()` method. Parameters algorithm:String the name of the RNG algorithm. See the `SecureRandom` section in the Java Security Standard Algorithm Names Specification for information about standard RNG algorithm names. provider:String the name of the provider. Returns:SecureRandom the new `SecureRandom` object Exceptions NoSuchAlgorithmException: if a `SecureRandomSpi` implementation for the specified algorithm is not available from the specified provider NoSuchProviderException: if the specified provider is not registered in the security provider list IllegalArgumentException: if the provider name is `null` or empty NullPointerException: if `algorithm` is `null` Since 1.2 See Also `Provider`

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

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 Security.getProviders() method.

Parameters

algorithm:String: the name of the RNG algorithm. See the SecureRandom section in the Java Security Standard Algorithm Names Specification for information about standard RNG algorithm names.
provider:String: the name of the provider.

Returns:SecureRandom

the new SecureRandom object

Exceptions

NoSuchAlgorithmException:: if a SecureRandomSpi implementation for the specified algorithm is not available from the specified provider
NoSuchProviderException:: if the specified provider is not registered in the security provider list
IllegalArgumentException:: if the provider name is null or empty
NullPointerException:: if algorithm is null

Since

1.2

See Also

Provider

getInstance back to summary

getInstance	back to summary
public static SecureRandom getInstance(String algorithm, Provider provider) throws NoSuchAlgorithmException 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. Note that the specified provider does not have to be registered in the provider list. Parameters algorithm:String the name of the RNG algorithm. See the `SecureRandom` section in the Java Security Standard Algorithm Names Specification for information about standard RNG algorithm names. provider:Provider the provider. Returns:SecureRandom the new `SecureRandom` object Exceptions NoSuchAlgorithmException: if a `SecureRandomSpi` implementation for the specified algorithm is not available from the specified `Provider` object IllegalArgumentException: if the specified provider is `null` NullPointerException: if `algorithm` is `null` Since 1.4 See Also `Provider`

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

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. Note that the specified provider does not have to be registered in the provider list.

Parameters

algorithm:String: the name of the RNG algorithm. See the SecureRandom section in the Java Security Standard Algorithm Names Specification for information about standard RNG algorithm names.
provider:Provider: the provider.

Returns:SecureRandom

the new SecureRandom object

Exceptions

NoSuchAlgorithmException:: if a SecureRandomSpi implementation for the specified algorithm is not available from the specified Provider object
IllegalArgumentException:: if the specified provider is null
NullPointerException:: if algorithm is null

Since

1.4

See Also

Provider

getInstance back to summary

getInstance	back to summary
public static SecureRandom getInstance(String algorithm, SecureRandomParameters params) throws NoSuchAlgorithmException Returns a `SecureRandom` object that implements the specified Random Number Generator (RNG) algorithm and supports the specified `SecureRandomParameters` request. 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 and the specified `SecureRandomParameters` is returned. Note that the list of registered providers may be retrieved via the `Security.getProviders()` method. Implementation Note The JDK Reference Implementation additionally uses the `jdk.security.provider.preferred` property to determine the preferred provider order for the specified algorithm. This may be different from the order of providers returned by `Security.getProviders()`. Parameters algorithm:String the name of the RNG algorithm. See the `SecureRandom` section in the Java Security Standard Algorithm Names Specification for information about standard RNG algorithm names. params:SecureRandomParameters the `SecureRandomParameters` the newly created `SecureRandom` object must support. Returns:SecureRandom the new `SecureRandom` object Exceptions NoSuchAlgorithmException: if no Provider supports a `SecureRandomSpi` implementation for the specified algorithm and parameters IllegalArgumentException: if the specified params is `null` NullPointerException: if `algorithm` is `null` Since 9 See Also `Provider`

public static SecureRandom getInstance(String algorithm, SecureRandomParameters params) throws NoSuchAlgorithmException

Returns a SecureRandom object that implements the specified Random Number Generator (RNG) algorithm and supports the specified SecureRandomParameters request.

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 and the specified SecureRandomParameters is returned.

Note that the list of registered providers may be retrieved via the Security.getProviders() method.

Implementation Note

The JDK Reference Implementation additionally uses the jdk.security.provider.preferred property to determine the preferred provider order for the specified algorithm. This may be different from the order of providers returned by Security.getProviders().

Parameters

algorithm:String: the name of the RNG algorithm. See the SecureRandom section in the Java Security Standard Algorithm Names Specification for information about standard RNG algorithm names.
params:SecureRandomParameters: the SecureRandomParameters the newly created SecureRandom object must support.

Returns:SecureRandom

the new SecureRandom object

Exceptions

NoSuchAlgorithmException:: if no Provider supports a SecureRandomSpi implementation for the specified algorithm and parameters
IllegalArgumentException:: if the specified params is null
NullPointerException:: if algorithm is null

Since

See Also

Provider

getInstance back to summary

getInstance	back to summary
public static SecureRandom getInstance(String algorithm, SecureRandomParameters params, String provider) throws NoSuchAlgorithmException, NoSuchProviderException Returns a `SecureRandom` object that implements the specified Random Number Generator (RNG) algorithm and supports the specified `SecureRandomParameters` request. 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 `Security.getProviders()` method. Parameters algorithm:String the name of the RNG algorithm. See the `SecureRandom` section in the Java Security Standard Algorithm Names Specification for information about standard RNG algorithm names. params:SecureRandomParameters the `SecureRandomParameters` the newly created `SecureRandom` object must support. provider:String the name of the provider. Returns:SecureRandom the new `SecureRandom` object Exceptions NoSuchAlgorithmException: if the specified provider does not support a `SecureRandomSpi` implementation for the specified algorithm and parameters NoSuchProviderException: if the specified provider is not registered in the security provider list IllegalArgumentException: if the provider name is `null` or empty, or params is `null` NullPointerException: if `algorithm` is `null` Since 9 See Also `Provider`

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

Returns a SecureRandom object that implements the specified Random Number Generator (RNG) algorithm and supports the specified SecureRandomParameters request.

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 Security.getProviders() method.

Parameters

algorithm:String: the name of the RNG algorithm. See the SecureRandom section in the Java Security Standard Algorithm Names Specification for information about standard RNG algorithm names.
params:SecureRandomParameters: the SecureRandomParameters the newly created SecureRandom object must support.
provider:String: the name of the provider.

Returns:SecureRandom

the new SecureRandom object

Exceptions

NoSuchAlgorithmException:: if the specified provider does not support a SecureRandomSpi implementation for the specified algorithm and parameters
NoSuchProviderException:: if the specified provider is not registered in the security provider list
IllegalArgumentException:: if the provider name is null or empty, or params is null
NullPointerException:: if algorithm is null

Since

See Also

Provider

getInstance back to summary

getInstance	back to summary
public static SecureRandom getInstance(String algorithm, SecureRandomParameters params, Provider provider) throws NoSuchAlgorithmException Returns a `SecureRandom` object that implements the specified Random Number Generator (RNG) algorithm and supports the specified `SecureRandomParameters` request. A new `SecureRandom` object encapsulating the `SecureRandomSpi` implementation from the specified provider is returned. Note that the specified provider does not have to be registered in the provider list. Parameters algorithm:String the name of the RNG algorithm. See the `SecureRandom` section in the Java Security Standard Algorithm Names Specification for information about standard RNG algorithm names. params:SecureRandomParameters the `SecureRandomParameters` the newly created `SecureRandom` object must support. provider:Provider the provider. Returns:SecureRandom the new `SecureRandom` object Exceptions NoSuchAlgorithmException: if the specified provider does not support a `SecureRandomSpi` implementation for the specified algorithm and parameters IllegalArgumentException: if the specified provider or params is `null` NullPointerException: if `algorithm` is `null` Since 9 See Also `Provider`

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

Returns a SecureRandom object that implements the specified Random Number Generator (RNG) algorithm and supports the specified SecureRandomParameters request.

Parameters

algorithm:String: the name of the RNG algorithm. See the SecureRandom section in the Java Security Standard Algorithm Names Specification for information about standard RNG algorithm names.
params:SecureRandomParameters: the SecureRandomParameters the newly created SecureRandom object must support.
provider:Provider: the provider.

Returns:SecureRandom

the new SecureRandom object

Exceptions

NoSuchAlgorithmException:: if the specified provider does not support a SecureRandomSpi implementation for the specified algorithm and parameters
IllegalArgumentException:: if the specified provider or params is null
NullPointerException:: if algorithm is null

Since

See Also

Provider

getInstanceStrong back to summary

getInstanceStrong	back to summary
public static SecureRandom getInstanceStrong() throws NoSuchAlgorithmException Returns a `SecureRandom` object that was selected by using the algorithms/providers specified in the `securerandom.strongAlgorithms` `Security` property. Some situations require strong random values, such as when creating high-value/long-lived secrets like RSA public/private keys. To help guide applications in selecting a suitable strong `SecureRandom` implementation, Java distributions include a list of known strong `SecureRandom` implementations in the `securerandom.strongAlgorithms` Security property. Every implementation of the Java platform is required to support at least one strong `SecureRandom` implementation. Returns:SecureRandom a strong `SecureRandom` implementation as indicated by the `securerandom.strongAlgorithms` Security property Exceptions NoSuchAlgorithmException: if no algorithm is available Since 1.8 See Also `Security#getProperty(String)`

public static SecureRandom getInstanceStrong() throws NoSuchAlgorithmException

Returns a SecureRandom object that was selected by using the algorithms/providers specified in the securerandom.strongAlgorithms Security property.

Some situations require strong random values, such as when creating high-value/long-lived secrets like RSA public/private keys. To help guide applications in selecting a suitable strong SecureRandom implementation, Java distributions include a list of known strong SecureRandom implementations in the securerandom.strongAlgorithms Security property.

Every implementation of the Java platform is required to support at least one strong SecureRandom implementation.

Returns:SecureRandom

a strong SecureRandom implementation as indicated by the securerandom.strongAlgorithms Security property

Exceptions

NoSuchAlgorithmException:: if no algorithm is available

Since

1.8

See Also

Security#getProperty(String)

getParameters back to summary

getParameters	back to summary
public SecureRandomParameters getParameters() Returns the effective `SecureRandomParameters` for this `SecureRandom` instance. The returned value can be different from the `SecureRandomParameters` object passed into a `getInstance` method, but it cannot change during the lifetime of this `SecureRandom` object. A caller can use the returned value to find out what features this `SecureRandom` supports. Returns:SecureRandomParameters the effective `SecureRandomParameters` parameters, or `null` if no parameters were used. Since 9 See Also `SecureRandomSpi`

public SecureRandomParameters getParameters()

Returns the effective SecureRandomParameters for this SecureRandom instance.

The returned value can be different from the SecureRandomParameters object passed into a getInstance method, but it cannot change during the lifetime of this SecureRandom object.

A caller can use the returned value to find out what features this SecureRandom supports.

Returns:SecureRandomParameters: the effective SecureRandomParameters parameters, or null if no parameters were used.
Since: 9
See Also: SecureRandomSpi

getProvider back to summary

getProvider	back to summary
public final Provider getProvider() Returns the provider of this `SecureRandom` object. Returns:Provider the provider of this `SecureRandom` object.

public final Provider getProvider()

Returns the provider of this SecureRandom object.

Returns:Provider: the provider of this SecureRandom object.

getProviderName	back to summary
private String getProviderName()

getSeed back to summary

getSeed	back to summary
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. Parameters numBytes:int the number of seed bytes to generate. Returns:byte[] the seed bytes. Exceptions IllegalArgumentException: if `numBytes` is negative See Also `setSeed`

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.

Parameters

numBytes:int: the number of seed bytes to generate.

Returns:byte[]

the seed bytes.

Exceptions

IllegalArgumentException:: if numBytes is negative

See Also

setSeed

getThreadSafe	back to summary
private boolean getThreadSafe()

longToByteArray	back to summary
private static byte[] longToByteArray(long l) Helper function to convert a long into a byte array (least significant byte first).

next back to summary

next	back to summary
protected final int next(int numBits) Overrides java.util.Random.next. 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 the methods inherited from that class (for example, `nextInt`, `nextLong`, and `nextFloat`). Parameters numBits:int number of pseudo-random bits to be generated, where `0 <= numBits <= 32`. Returns:int an `int` containing the user-specified number of pseudo-random bits (right justified, with leading zeros). Annotations @Override

protected final int next(int numBits)

Overrides java.util.Random.next.

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 the methods inherited from that class (for example, nextInt, nextLong, and nextFloat).

Parameters

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

Returns:int

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

Annotations

@Override

nextBytes back to summary

nextBytes	back to summary
public void nextBytes(byte[] bytes) Overrides java.util.Random.nextBytes. Overrides default java.util.random.RandomGenerator.nextBytes. Generates a user-specified number of random bytes. Parameters bytes:byte[] the array to be filled in with random bytes. Annotations @Override Exceptions NullPointerException: if `bytes` is `null`

public void nextBytes(byte[] bytes)

Overrides java.util.Random.nextBytes.

Overrides default java.util.random.RandomGenerator.nextBytes.

Generates a user-specified number of random bytes.

Parameters

bytes:byte[]: the array to be filled in with random bytes.

Annotations

@Override

Exceptions

NullPointerException:: if bytes is null

nextBytes back to summary

nextBytes	back to summary
public void nextBytes(byte[] bytes, SecureRandomParameters params) Generates a user-specified number of random bytes with additional parameters. Parameters bytes:byte[] the array to be filled in with random bytes params:SecureRandomParameters additional parameters Exceptions NullPointerException: if `bytes` is `null` UnsupportedOperationException: if the underlying provider implementation has not overridden this method IllegalArgumentException: if `params` is `null`, illegal or unsupported by this `SecureRandom` Since 9

public void nextBytes(byte[] bytes, SecureRandomParameters params)

Generates a user-specified number of random bytes with additional parameters.

Parameters

bytes:byte[]: the array to be filled in with random bytes
params:SecureRandomParameters: additional parameters

Exceptions

NullPointerException:: if bytes is null
UnsupportedOperationException:: if the underlying provider implementation has not overridden this method
IllegalArgumentException:: if params is null, illegal or unsupported by this SecureRandom

Since

reseed back to summary

reseed	back to summary
public void reseed() Reseeds this `SecureRandom` with entropy input read from its entropy source. Exceptions UnsupportedOperationException: if the underlying provider implementation has not overridden this method. Since 9

public void reseed()

Reseeds this SecureRandom with entropy input read from its entropy source.

Exceptions

UnsupportedOperationException:: if the underlying provider implementation has not overridden this method.

Since

reseed back to summary

reseed	back to summary
public void reseed(SecureRandomParameters params) Reseeds this `SecureRandom` with entropy input read from its entropy source with additional parameters. Note that entropy is obtained from an entropy source. While some data in `params` may contain entropy, its main usage is to provide diversity. Parameters params:SecureRandomParameters extra parameters Exceptions UnsupportedOperationException: if the underlying provider implementation has not overridden this method. IllegalArgumentException: if `params` is `null`, illegal or unsupported by this `SecureRandom` Since 9

public void reseed(SecureRandomParameters params)

Reseeds this SecureRandom with entropy input read from its entropy source with additional parameters.

Note that entropy is obtained from an entropy source. While some data in params may contain entropy, its main usage is to provide diversity.

Parameters

params:SecureRandomParameters: extra parameters

Exceptions

UnsupportedOperationException:: if the underlying provider implementation has not overridden this method.
IllegalArgumentException:: if params is null, illegal or unsupported by this SecureRandom

Since

setSeed back to summary

setSeed	back to summary
public void setSeed(byte[] seed) Reseeds this random object with the given seed. The seed supplements, rather than replaces, the existing seed. Thus, repeated calls are guaranteed never to reduce randomness. A PRNG `SecureRandom` will not seed itself automatically if `setSeed` is called before any `nextBytes` or `reseed` calls. The caller should make sure that the `seed` argument contains enough entropy for the security of this `SecureRandom`. Parameters seed:byte[] the seed. Exceptions NullPointerException: if `seed` is `null` See Also `getSeed`

public void setSeed(byte[] seed)

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

A PRNG SecureRandom will not seed itself automatically if setSeed is called before any nextBytes or reseed calls. The caller should make sure that the seed argument contains enough entropy for the security of this SecureRandom.

Parameters

seed:byte[]: the seed.

Exceptions

NullPointerException:: if seed is null

See Also

getSeed

setSeed back to summary

setSeed	back to summary
public void setSeed(long seed) Overrides java.util.Random.setSeed. 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. A PRNG `SecureRandom` will not seed itself automatically if `setSeed` is called before any `nextBytes` or `reseed` calls. The caller should make sure that the `seed` argument contains enough entropy for the security of this `SecureRandom`. This method is defined for compatibility with `java.util.Random`. Parameters seed:long the seed. Annotations @Override See Also `getSeed`

public void setSeed(long seed)

Overrides java.util.Random.setSeed.

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.

Parameters

seed:long: the seed.

Annotations

@Override

See Also

getSeed

toString back to summary

toString	back to summary
public String toString() Overrides java.lang.Object.toString. Returns a Human-readable string representation of this `SecureRandom`. Returns:String the string representation Annotations @Override

public String toString()

Overrides java.lang.Object.toString.

Returns a Human-readable string representation of this SecureRandom.

Returns:String

the string representation

Annotations

@Override

public Class SecureRandom

Thread safety

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private final Class SecureRandom.StrongPatternHolder

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail