Module java.base
Package java.security

## Class SecureRandomSpi

- java.lang.Object
- - java.security.SecureRandomSpi

- All Implemented Interfaces:
    `Serializable`

      public abstract class SecureRandomSpi
      extends Object
      implements Serializable

  This class defines the Service Provider Interface (SPI) for the `SecureRandom` class.

  All the abstract methods in this class must be implemented by each service provider who wishes to supply the implementation of a cryptographically strong pseudo-random number generator.

  Implementation Requirements:
    If the `SecureRandomSpi(SecureRandomParameters)` constructor is overridden in an implementation, it will always be called whenever a `SecureRandom` is instantiated. Precisely, if an object is instantiated with one of `SecureRandom`'s `getInstance` methods without a `SecureRandomParameters` parameter, the constructor will be called with a `null` argument and the implementation is responsible for creating its own `SecureRandomParameters` parameter for use when `engineGetParameters()` is called. If an object is instantiated with one of `SecureRandom`'s `getInstance` methods with a `SecureRandomParameters` argument, the constructor will be called with that argument. The `engineGetParameters()` method must not return `null`.

    Otherwise, if the `SecureRandomSpi(SecureRandomParameters)` constructor is not overridden in an implementation, the `SecureRandomSpi()` constructor must be overridden and it will be called if an object is instantiated with one of `SecureRandom`'s `getInstance` methods without a `SecureRandomParameters` argument. Calling one of `SecureRandom`'s `getInstance` methods with a `SecureRandomParameters` argument will never return an instance of this implementation. The `engineGetParameters()` method must return `null`.

    See `SecureRandom` for additional details on thread safety. By default, a `SecureRandomSpi` implementation is considered to be not safe for use by multiple concurrent threads and `SecureRandom` will synchronize access to each of the applicable engine methods (see `SecureRandom` for the list of methods). However, if a `SecureRandomSpi` implementation is thread-safe, the service provider attribute "ThreadSafe" should be set to "true" during its registration, as follows:

    >      put("SecureRandom.AlgName ThreadSafe", "true");

    or

    >      putService(new Service(this, "SecureRandom", "AlgName", className,
    >               null, Map.of("ThreadSafe", "true")));

    `SecureRandom` will call the applicable engine methods without any synchronization.
  Since:
    1.2
  See Also:
    Serialized Form

- - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `` | `SecureRandomSpi()` | Constructor without a parameter.
    `protected` | `SecureRandomSpi​(SecureRandomParameters params)` | Constructor with a parameter.

  - ### Method Summary

    Modifier and Type | Method | Description
    --- | --- | ---
    `protected abstract byte[]` | `engineGenerateSeed​(int numBytes)` | Returns the given number of seed bytes.
    `protected SecureRandomParameters` | `engineGetParameters()` | Returns the effective `SecureRandomParameters` for this `SecureRandom` instance.
    `protected abstract void` | `engineNextBytes​(byte[] bytes)` | Generates a user-specified number of random bytes.
    `protected void` | `engineNextBytes​(byte[] bytes, SecureRandomParameters params)` | Generates a user-specified number of random bytes with additional parameters.
    `protected void` | `engineReseed​(SecureRandomParameters params)` | Reseeds this random object with entropy input read from its entropy source with additional parameters.
    `protected abstract void` | `engineSetSeed​(byte[] seed)` | Reseeds this random object with the given seed.
    `String` | `toString()` | Returns a Human-readable string representation of this `SecureRandom`.

    - ### Methods declared in class java.lang.Object

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

- - ### Constructor Detail

    - #### SecureRandomSpi

          public SecureRandomSpi()

      Constructor without a parameter.

    - #### SecureRandomSpi

          protected SecureRandomSpi​(SecureRandomParameters params)

      Constructor with a parameter.
      Parameters:
        `params` - the `SecureRandomParameters` object. This argument can be `null`.
      Throws:
        `IllegalArgumentException` - if `params` is unrecognizable or unsupported by this `SecureRandom`
      Since:
        9

  - ### Method Detail

    - #### engineSetSeed

          protected abstract void engineSetSeed​(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.
      Parameters:
        `seed` - the seed.

    - #### engineNextBytes

          protected abstract void engineNextBytes​(byte[] bytes)

      Generates a user-specified number of random bytes.

      Some random number generators can only generate a limited amount of random bytes per invocation. If the size of `bytes` is greater than this limit, the implementation should invoke its generation process multiple times to completely fill the buffer before returning from this method.

      Parameters:
        `bytes` - the array to be filled in with random bytes.

    - #### engineNextBytes

          protected void engineNextBytes​(byte[] bytes,
                                         SecureRandomParameters params)

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

      Some random number generators can only generate a limited amount of random bytes per invocation. If the size of `bytes` is greater than this limit, the implementation should invoke its generation process multiple times to completely fill the buffer before returning from this method.

      Implementation Requirements:
        The default implementation throws an `UnsupportedOperationException`.
      Parameters:
        `bytes` - the array to be filled in with random bytes
        `params` - additional parameters
      Throws:
        `UnsupportedOperationException` - if the implementation has not overridden this method
        `IllegalArgumentException` - if `params` is `null`, illegal or unsupported by this `SecureRandom`
      Since:
        9

    - #### engineGenerateSeed

          protected abstract byte[] engineGenerateSeed​(int numBytes)

      Returns the given number of seed bytes. This call may be used to seed other random number generators.
      Parameters:
        `numBytes` - the number of seed bytes to generate.
      Returns:
        the seed bytes.

    - #### engineReseed

          protected void engineReseed​(SecureRandomParameters params)

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

      If this method is called by `SecureRandom.reseed()`, `params` will be `null`.

      Do not override this method if the implementation does not support reseeding.

      Implementation Requirements:
        The default implementation throws an `UnsupportedOperationException`.
      Parameters:
        `params` - extra parameters, can be `null`.
      Throws:
        `UnsupportedOperationException` - if the implementation has not overridden this method
        `IllegalArgumentException` - if `params` is illegal or unsupported by this `SecureRandom`
      Since:
        9

    - #### engineGetParameters

          protected SecureRandomParameters engineGetParameters()

      Returns the effective `SecureRandomParameters` for this `SecureRandom` instance.
      Implementation Requirements:
        The default implementation returns `null`.
      Returns:
        the effective `SecureRandomParameters` parameters, or `null` if no parameters were used.
      Since:
        9

    - #### toString

          public String toString()

      Returns a Human-readable string representation of this `SecureRandom`.
      Overrides:
        `toString` in class `Object`
      Returns:
        the string representation