Class 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

Constructors

Modifier Constructor Description
SecureRandomSpi()

Constructor without a parameter.
protected SecureRandomSpi​(SecureRandomParameters params)

Constructor with a parameter.

Methods

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

Constructors

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

Methods

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

© 1993, 2020, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/security/SecureRandomSpi.html