Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| JavaTM 2 Platform Std. Ed. v1.4.1
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## java.security
Class SecureRandom

    java.lang.Object
      |
      +--java.util.Random
            |
            +--java.security.SecureRandom

All Implemented Interfaces:
  Serializable

public class SecureRandom
extends Random

This class provides a cryptographically strong pseudo-random number generator (PRNG). A cryptographically strong pseudo-random number minimally complies with the statistical random number generator tests specified in FIPS 140-2, Security Requirements for Cryptographic Modules, section 4.9.1. Additionally, SecureRandom must produce non-deterministic output and therefore it is required that the seed material be unpredictable and that output of SecureRandom be cryptographically strong sequences as described in RFC 1750: Randomness Recommendations for Security.

Like other algorithm-based classes in Java Security, SecureRandom provides implementation-independent algorithms, whereby a caller (application code) requests a particular PRNG algorithm and is handed back a SecureRandom object for that algorithm. It is also possible, if desired, to request a particular algorithm from a particular provider. See the `getInstance` methods.

Thus, there are two ways to request a SecureRandom object: by specifying either just an algorithm name, or both an algorithm name and a package provider.

- If just an algorithm name is specified, as in:

            SecureRandom random = SecureRandom.getInstance("SHA1PRNG");

  the system will determine if there is an implementation of the algorithm requested available in the environment, and if there is more than one, if there is a preferred one.

- If both an algorithm name and a package provider are specified, as in:

            SecureRandom random = SecureRandom.getInstance("SHA1PRNG", "SUN");

  the system will determine if there is an implementation of the algorithm in the package requested, and throw an exception if there is not.

The SecureRandom implementation attempts to completely randomize the internal state of the generator itself unless the caller follows the call to a `getInstance` method with a call to the `setSeed` method:

          SecureRandom random = SecureRandom.getInstance("SHA1PRNG");
          random.setSeed(seed);

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

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

The caller may also invoke the `generateSeed` method to generate a given number of seed bytes (to seed other random number generators, for example):

          byte seed[] = random.generateSeed(20);

See Also:
  `SecureRandomSpi`, `Random`, Serialized Form

Constructor Summary
`` | `SecureRandom()` By using this constructor, the caller obtains a SecureRandom object containing the implementation from the highest-priority installed provider that has a SecureRandom implementation.
`` | `SecureRandom(byte[] seed)` By using this constructor, the caller obtains a SecureRandom object containing the implementation from the highest-priority installed provider that has a SecureRandom implementation.
`protected` | `SecureRandom(SecureRandomSpi secureRandomSpi, Provider provider)` Creates a SecureRandom object.

Method Summary
`byte[]` | `generateSeed(int numBytes)` Returns the given number of seed bytes, computed using the seed generation algorithm that this class uses to seed itself.
`static SecureRandom` | `getInstance(String algorithm)` Generates a SecureRandom object that implements the specified Pseudo Random Number Generator (PRNG) algorithm.
`static SecureRandom` | `getInstance(String algorithm, Provider provider)` Generates a SecureRandom object for the specified PRNG algorithm, as supplied from the specified provider, if such a PRNG implementation is available from the provider.
`static SecureRandom` | `getInstance(String algorithm, String provider)` Generates a SecureRandom object for the specified PRNG algorithm, as supplied from the specified provider, if such a PRNG implementation is available from the provider.
`Provider` | `getProvider()` Returns the provider of this SecureRandom object.
`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.
`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
`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()

  By using this constructor, the caller obtains a SecureRandom object containing the implementation from the highest-priority installed provider that has a SecureRandom implementation.

  Note that this instance of SecureRandom has not been seeded. A call to the `setSeed` method will seed the SecureRandom object. If a call is not made to `setSeed`, the first call to the `nextBytes` method will force the SecureRandom object to seed itself.

  This constructor is provided for backwards compatibility. The caller is encouraged to use one of the alternative `getInstance` methods to obtain a SecureRandom object.

### SecureRandom

    public SecureRandom(byte[] seed)

  By using this constructor, the caller obtains a SecureRandom object containing the implementation from the highest-priority installed provider that has a SecureRandom implementation. This constructor uses a user-provided seed in preference to the self-seeding algorithm referred to in the empty constructor description. It may be preferable to the empty constructor if the caller has access to high-quality random bytes from some physical device (for example, a radiation detector or a noisy diode).

  This constructor is provided for backwards compatibility. The caller is encouraged to use one of the alternative `getInstance` methods to obtain a SecureRandom object, and then to call the `setSeed` method to seed it.

Parameters:
  `seed` - the seed.

### SecureRandom

    protected SecureRandom(SecureRandomSpi secureRandomSpi,
                           Provider provider)

  Creates a SecureRandom object.

Parameters:
  `secureRandomSpi` - the SecureRandom implementation.
  `provider` - the provider.

Method Detail

### getInstance

    public static SecureRandom getInstance(String algorithm)
                                    throws NoSuchAlgorithmException

  Generates a SecureRandom object that implements the specified Pseudo Random Number Generator (PRNG) algorithm. If the default provider package provides an implementation of the requested PRNG, an instance of SecureRandom containing that implementation is returned. If the PRNG is not available in the default package, other packages are searched.

  Note that the returned instance of SecureRandom has not been seeded. A call to the `setSeed` method will seed the SecureRandom object. If a call is not made to `setSeed`, the first call to the `nextBytes` method will force the SecureRandom object to seed itself.

  Parameters:
    `algorithm` - the name of the PRNG algorithm. See Appendix A in the Java Cryptography Architecture API Specification & Reference for information about standard PRNG algorithm names.
  Returns:
    the new SecureRandom object.
  Throws:
    `NoSuchAlgorithmException` - if the PRNG algorithm is not available in the caller's environment.
  Since:
    1.2

### getInstance

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

  Generates a SecureRandom object for the specified PRNG algorithm, as supplied from the specified provider, if such a PRNG implementation is available from the provider.

  Note that the returned instance of SecureRandom has not been seeded. A call to the `setSeed` method will seed the SecureRandom object. If a call is not made to `setSeed`, the first call to the `nextBytes` method will force the SecureRandom object to seed itself.

  Parameters:
    `algorithm` - the name of the PRNG algorithm. See Appendix A in the Java Cryptography Architecture API Specification & Reference for information about standard PRNG algorithm names.
    `provider` - the name of the provider.
  Returns:
    the new SecureRandom object.
  Throws:
    `NoSuchAlgorithmException` - if the requested PRNG implementation is not available from the provider.
    `NoSuchProviderException` - if the provider has not been configured.
    `IllegalArgumentException` - if the provider name is null or empty.
  Since:
    1.2
  See Also:
    `Provider`

### getInstance

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

  Generates a SecureRandom object for the specified PRNG algorithm, as supplied from the specified provider, if such a PRNG implementation is available from the provider. Note: the `provider` doesn't have to be registered.

  Note that the returned instance of SecureRandom has not been seeded. A call to the `setSeed` method will seed the SecureRandom object. If a call is not made to `setSeed`, the first call to the `nextBytes` method will force the SecureRandom object to seed itself.

  Parameters:
    `algorithm` - the name of the PRNG algorithm. See Appendix A in the Java Cryptography Architecture API Specification & Reference for information about standard PRNG algorithm names.
    `provider` - the provider.
  Returns:
    the new SecureRandom object.
  Throws:
    `NoSuchAlgorithmException` - if the requested PRNG implementation is not available from the provider.
    `IllegalArgumentException` - if the `provider` is null.
  Since:
    1.4
  See Also:
    `Provider`

### getProvider

    public final Provider getProvider()

  Returns the provider of this SecureRandom object.

  Returns:
    the provider of this SecureRandom object.

### 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.
  See Also:
    `getSeed(int)`

### 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 `Random`
  Parameters:
    `seed` - the seed.
  See Also:
    `getSeed(int)`

### nextBytes

    public void nextBytes(byte[] bytes)

  Generates a user-specified number of random bytes. This method is used as the basis of all random entities returned by this class (except seed bytes).

  Overrides:
    `nextBytes` in class `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 `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).

### 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 alternative `getInstance` methods to obtain a SecureRandom object, and then call the `generateSeed` method to obtain seed bytes from that object.

  Parameters:
    `numBytes` - the number of seed bytes to generate.
  Returns:
    the seed bytes.
  See Also:
    `setSeed(byte[])`

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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| JavaTM 2 Platform Std. Ed. v1.4.1
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Submit a bug or feature
For further API reference and developer documentation, see Java 2 SDK SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Copyright 2002 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.