Class SecureRandom

java.lang.Object
java.util.Random
java.security.SecureRandom
All Implemented Interfaces:
Serializable,RandomGenerator
public classSecureRandomextendsRandom
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 inFIPS 140-2, Security Requirements for Cryptographic Modules, section 4.9.1. Additionally,SecureRandom must produce non-deterministic output. Therefore, any seed material passed to aSecureRandom object must be unpredictable, and allSecureRandom output sequences must be cryptographically strong, as described inRFC 4086: Randomness Requirements for Security.

ManySecureRandom 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 aSecureRandom instance via the no-argument constructor or one of thegetInstance 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 aSecureRandom 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 aSecureRandom until it's actually used, but the effective instantiate parameters must be determined right after it's created andgetParameters() should always return the same result unchanged.

Typical callers ofSecureRandom invoke the following methods to retrieve random bytes:

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

Callers may also invoke thegenerateSeed(int) 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 PRNGSecureRandom object is not seeded (except if it is created bySecureRandom(byte[])). The first call tonextBytes will force it to seed itself from an implementation- specific entropy source. This self-seeding will not occur ifsetSeed was previously called.

ASecureRandom can be reseeded at any time by calling thereseed orsetSeed method. Thereseed method reads entropy input from its entropy source to reseed itself. ThesetSeed method requires the caller to provide the seed.

Please note thatreseed may not be supported by allSecureRandom implementations.

SomeSecureRandom implementations may accept aSecureRandomParameters parameter in itsnextBytes(byte[], SecureRandomParameters) andreseed(SecureRandomParameters) methods to further control the behavior of the methods.

Note: Depending on the implementation, thegenerateSeed,reseed andnextBytes 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.
Implementation Requirements:
ASecureRandom service provider can advertise that it is thread-safe by setting theservice provider attribute "ThreadSafe" to "true" when registering the provider. Otherwise, this class will instead synchronize access to the following methods of theSecureRandomSpi implementation:
Since:
1.1
External Specifications
See Also:

  • Constructor Details

    • SecureRandom

      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 newSecureRandom object encapsulating theSecureRandomSpi implementation from the first provider that supports aSecureRandom (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 theSecurity.getProviders() method.

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

    • SecureRandom

      public SecureRandom(byte[] seed)
      Constructs a secure random number generator (RNG) implementing the default random number algorithm. TheSecureRandom instance is seeded with the specified seed bytes.

      This constructor traverses the list of registered security Providers, starting with the most preferred Provider. A newSecureRandom object encapsulating theSecureRandomSpi implementation from the first provider that supports aSecureRandom (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 theSecurity.getProviders() method.

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

      Parameters:
      seed - the seed.
      Throws:
      NullPointerException - ifseed isnull

    • SecureRandom

      protected SecureRandom(SecureRandomSpi secureRandomSpi,Provider provider)
      Creates aSecureRandom object.
      Parameters:
      secureRandomSpi - theSecureRandom implementation.
      provider - the provider.

  • Method Details

    • getInstance

      public static SecureRandom getInstance(String algorithm) throwsNoSuchAlgorithmException
      Returns aSecureRandom 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 newSecureRandom object encapsulating theSecureRandomSpi implementation from the first provider that supports the specified algorithm is returned.

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

      Implementation Note:
      The JDK Reference Implementation additionally uses thejdk.security.provider.preferredSecurity property to determine the preferred provider order for the specified algorithm. This may be different from the order of providers returned bySecurity.getProviders().
      Parameters:
      algorithm - the name of the RNG algorithm. See theSecureRandom section in the Java Security Standard Algorithm Names Specification for information about standard RNG algorithm names.
      Returns:
      the newSecureRandom object
      Throws:
      NoSuchAlgorithmException - if noProvider supports aSecureRandomSpi implementation for the specified algorithm
      NullPointerException - ifalgorithm isnull
      Since:
      1.2
      See Also:

    • getInstance

      public static SecureRandom getInstance(String algorithm,String provider) throwsNoSuchAlgorithmException,NoSuchProviderException
      Returns aSecureRandom object that implements the specified Random Number Generator (RNG) algorithm.

      A newSecureRandom object encapsulating theSecureRandomSpi 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 theSecurity.getProviders() method.

      Parameters:
      algorithm - the name of the RNG algorithm. See theSecureRandom section in the Java Security Standard Algorithm Names Specification for information about standard RNG algorithm names.
      provider - the name of the provider.
      Returns:
      the newSecureRandom object
      Throws:
      IllegalArgumentException - if the provider name isnull or empty
      NoSuchAlgorithmException - if aSecureRandomSpi 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
      NullPointerException - ifalgorithm isnull
      Since:
      1.2
      See Also:

    • getInstance

      public static SecureRandom getInstance(String algorithm,Provider provider) throwsNoSuchAlgorithmException
      Returns aSecureRandom object that implements the specified Random Number Generator (RNG) algorithm.

      A newSecureRandom object encapsulating theSecureRandomSpi implementation from the specified provider is returned. Note that the specified provider does not have to be registered in the provider list.

      Parameters:
      algorithm - the name of the RNG algorithm. See theSecureRandom section in the Java Security Standard Algorithm Names Specification for information about standard RNG algorithm names.
      provider - the provider.
      Returns:
      the newSecureRandom object
      Throws:
      IllegalArgumentException - if the specified provider isnull
      NoSuchAlgorithmException - if aSecureRandomSpi implementation for the specified algorithm is not available from the specifiedProvider object
      NullPointerException - ifalgorithm isnull
      Since:
      1.4
      See Also:

    • getInstance

      public static SecureRandom getInstance(String algorithm,SecureRandomParameters params) throwsNoSuchAlgorithmException
      Returns aSecureRandom object that implements the specified Random Number Generator (RNG) algorithm and supports the specifiedSecureRandomParameters request.

      This method traverses the list of registered security providers, starting with the most preferred provider. A newSecureRandom object encapsulating theSecureRandomSpi implementation from the first provider that supports the specified algorithm and the specifiedSecureRandomParameters is returned.

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

      Implementation Note:
      The JDK Reference Implementation additionally uses thejdk.security.provider.preferred property to determine the preferred provider order for the specified algorithm. This may be different from the order of providers returned bySecurity.getProviders().
      Parameters:
      algorithm - the name of the RNG algorithm. See theSecureRandom section in the Java Security Standard Algorithm Names Specification for information about standard RNG algorithm names.
      params - theSecureRandomParameters the newly createdSecureRandom object must support.
      Returns:
      the newSecureRandom object
      Throws:
      IllegalArgumentException - if the specified params isnull
      NoSuchAlgorithmException - if no Provider supports aSecureRandomSpi implementation for the specified algorithm and parameters
      NullPointerException - ifalgorithm isnull
      Since:
      9
      See Also:

    • getInstance

      public static SecureRandom getInstance(String algorithm,SecureRandomParameters params,String provider) throwsNoSuchAlgorithmException,NoSuchProviderException
      Returns aSecureRandom object that implements the specified Random Number Generator (RNG) algorithm and supports the specifiedSecureRandomParameters request.

      A newSecureRandom object encapsulating theSecureRandomSpi 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 theSecurity.getProviders() method.

      Parameters:
      algorithm - the name of the RNG algorithm. See theSecureRandom section in the Java Security Standard Algorithm Names Specification for information about standard RNG algorithm names.
      params - theSecureRandomParameters the newly createdSecureRandom object must support.
      provider - the name of the provider.
      Returns:
      the newSecureRandom object
      Throws:
      IllegalArgumentException - if the provider name isnull or empty, or params isnull
      NoSuchAlgorithmException - if the specified provider does not support aSecureRandomSpi implementation for the specified algorithm and parameters
      NoSuchProviderException - if the specified provider is not registered in the security provider list
      NullPointerException - ifalgorithm isnull
      Since:
      9
      See Also:

    • getInstance

      public static SecureRandom getInstance(String algorithm,SecureRandomParameters params,Provider provider) throwsNoSuchAlgorithmException
      Returns aSecureRandom object that implements the specified Random Number Generator (RNG) algorithm and supports the specifiedSecureRandomParameters request.

      A newSecureRandom object encapsulating theSecureRandomSpi implementation from the specified provider is returned. Note that the specified provider does not have to be registered in the provider list.

      Parameters:
      algorithm - the name of the RNG algorithm. See theSecureRandom section in the Java Security Standard Algorithm Names Specification for information about standard RNG algorithm names.
      params - theSecureRandomParameters the newly createdSecureRandom object must support.
      provider - the provider.
      Returns:
      the newSecureRandom object
      Throws:
      IllegalArgumentException - if the specified provider or params isnull
      NoSuchAlgorithmException - if the specified provider does not support aSecureRandomSpi implementation for the specified algorithm and parameters
      NullPointerException - ifalgorithm isnull
      Since:
      9
      See Also:

    • getProvider

      public final Provider getProvider()
      Returns the provider of thisSecureRandom object.
      Returns:
      the provider of thisSecureRandom object.

    • getAlgorithm

      public String getAlgorithm()
      Returns the name of the algorithm implemented by thisSecureRandom object.
      Returns:
      the name of the algorithm orunknown if the algorithm name cannot be determined.
      Since:
      1.5

    • toString

      public String toString()
      Returns a Human-readable string representation of thisSecureRandom.
      Overrides:
      toString in class Object
      Returns:
      the string representation

    • getParameters

      public SecureRandomParameters getParameters()
      Returns the effectiveSecureRandomParameters for thisSecureRandom instance.

      The returned value can be different from theSecureRandomParameters object passed into agetInstance method, but it cannot change during the lifetime of thisSecureRandom object.

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

      Returns:
      the effectiveSecureRandomParameters parameters, ornull if no parameters were used.
      Since:
      9
      See Also:

    • setSeed

      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 PRNGSecureRandom will not seed itself automatically ifsetSeed is called before anynextBytes orreseed calls. The caller should make sure that theseed argument contains enough entropy for the security of thisSecureRandom.

      Parameters:
      seed - the seed.
      Throws:
      NullPointerException - ifseed isnull
      See Also:

    • setSeed

      public void setSeed(long seed)
      Reseeds this random object, using the eight bytes contained in the givenlong seed. The given seed supplements, rather than replaces, the existing seed. Thus, repeated calls are guaranteed never to reduce randomness.

      A PRNGSecureRandom will not seed itself automatically ifsetSeed is called before anynextBytes orreseed calls. The caller should make sure that theseed argument contains enough entropy for the security of thisSecureRandom.

      This method is defined for compatibility withjava.util.Random.

      Overrides:
      setSeed in class Random
      Parameters:
      seed - the seed.
      See Also:

    • nextBytes

      public void nextBytes(byte[] bytes)
      Generates a user-specified number of random bytes.
      Specified by:
      nextBytes in interface RandomGenerator
      Overrides:
      nextBytes in class Random
      Parameters:
      bytes - the array to be filled in with random bytes.
      Throws:
      NullPointerException - ifbytes isnull

    • nextBytes

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

    • 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 ajava.util.Random method, and serves to provide a source of random bits to all the methods inherited from that class (for example,nextInt,nextLong, andnextFloat).
      Overrides:
      next in class Random
      Parameters:
      numBits - number of pseudo-random bits to be generated, where0 <= numBits <= 32.
      Returns:
      anint containing the user-specified number of pseudo-random bits (right justified, with leading zeros).

    • getSeed

      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 alternativegetInstance methods to obtain aSecureRandom object, and then call thegenerateSeed method to obtain seed bytes from that object.

      Parameters:
      numBytes - the number of seed bytes to generate.
      Returns:
      the seed bytes.
      Throws:
      IllegalArgumentException - ifnumBytes is negative
      See Also:

    • 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.
      Throws:
      IllegalArgumentException - ifnumBytes is negative

    • getInstanceStrong

      public static SecureRandom getInstanceStrong() throwsNoSuchAlgorithmException
      Returns aSecureRandom object that was selected by using the algorithms/providers specified in the securerandom.strongAlgorithmsSecurity 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 strongSecureRandom implementation, Java distributions include a list of known strongSecureRandom implementations in thesecurerandom.strongAlgorithms Security property.

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

      Returns:
      a strongSecureRandom implementation as indicated by thesecurerandom.strongAlgorithms Security property
      Throws:
      NoSuchAlgorithmException - if no algorithm is available
      Since:
      1.8
      See Also:

    • reseed

      public void reseed()
      Reseeds thisSecureRandom with entropy input read from its entropy source.
      Throws:
      UnsupportedOperationException - if the underlying provider implementation has not overridden this method.
      Since:
      9

    • reseed

      public void reseed(SecureRandomParameters params)
      Reseeds thisSecureRandom with entropy input read from its entropy source with additional parameters.

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

      Parameters:
      params - extra parameters
      Throws:
      UnsupportedOperationException - if the underlying provider implementation has not overridden this method.
      IllegalArgumentException - ifparams isnull, illegal or unsupported by thisSecureRandom
      Since:
      9