Package java.security

Class SecureRandom

  • All Implemented Interfaces:
    java.io.Serializable
    public class SecureRandom
extends java.util.Random
    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 1750: Randomness Recommendations for Security.

    A caller obtains a SecureRandom instance via the no-argument constructor: 

     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.
    See Also:
    Random, Serialized Form

    • Constructor Summary

      Constructors 
      Constructor Description
      SecureRandom()
      Constructs a secure random number generator (RNG) implementing the default random number algorithm.
      SecureRandom​(byte[] seed)
      Constructs a secure random number generator (RNG) implementing the default random number algorithm.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      byte[] generateSeed​(int numBytes)
      Returns the given number of seed bytes, computed using the seed generation algorithm that this class uses to seed itself.
      protected int next​(int numBits)
      Generates an integer containing the user-specified number of pseudo-random bits (right justified, with leading zeros).
      void nextBytes​(byte[] bytes)
      Generates a user-specified number of random bytes.
      void setSeed​(byte[] seed)
      Reseeds this random object.
      void setSeed​(long seed)
      Reseeds this random object, using the eight bytes contained in the given long seed.

      • Methods inherited from class java.util.Random

        doubles, doubles, doubles, doubles, ints, ints, ints, ints, longs, longs, longs, longs, nextBoolean, nextDouble, nextFloat, nextGaussian, nextInt, nextInt, nextLong

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • SecureRandom

        public SecureRandom()
        Constructs a secure random number generator (RNG) implementing the default random number algorithm.

        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.

      • SecureRandom

        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.
        Parameters:
        seed - the seed.

    • Method Detail

      • setSeed

        public void setSeed​(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.
        Parameters:
        seed - the seed.

      • setSeed

        public void setSeed​(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.

        Overrides:
        setSeed in class java.util.Random
        Parameters:
        seed - the seed.

      • nextBytes

        public void nextBytes​(byte[] bytes)
        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.

        Overrides:
        nextBytes in class java.util.Random
        Parameters:
        bytes - the array to be filled in with random bytes.

      • 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 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).
        Overrides:
        next in class java.util.Random
        Parameters:
        numBits - number of pseudo-random bits to be generated, where 0 <= numBits <= 32.
        Returns:
        an int containing the user-specified number of pseudo-random bits (right justified, with leading zeros).

      • 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.