APIdia Launch Partner
Top Description Inners Fields Constructors Methods
sun.security.provider

public abstract Class AbstractDrbg

extends Object
Class Inheritance
Known Direct Subclasses
sun.security.provider.AbstractHashDrbg, sun.security.provider.CtrDrbg
Imports
sun.security.util.Debug, java.security.*, java.util.Arrays, .Objects
The abstract base class for all DRBGs. It is used as DRBG#impl.

This class has 5 abstract methods. 3 are defined by SP800-90A:

  1. generateAlgorithm(byte[], byte[])
  2. reseedAlgorithm(byte[], byte[]) (In fact this is not an abstract method, but any DRBG supporting reseeding must override it.)
  3. instantiateAlgorithm(byte[])
and 2 for implementation purpose:
  1. initEngine()
  2. chooseAlgorithmAndStrength
Although this class is not a child class of SecureRandomSpi, it implements all abstract methods there as final.

The initialization process of a DRBG is divided into 2 phases: configuration is eagerly called to set up parameters, and instantiation is lazily called only when nextBytes or reseed is called.

SecureRandom methods like reseed and nextBytes are not thread-safe. An implementation is required to protect shared access to instantiate states (instantiated, nonce) and DRBG states (v, c, key, reseedCounter, etc.).

Nested and Inner Type Summary

Modifier and TypeClass and Description
private static class
AbstractDrbg.NonceProvider

private static class
AbstractDrbg.SeederHolder

Field Summary

Modifier and TypeField and Description
protected String
algorithm

Algorithm used by this instance (SHA-512 or AES-256).

protected static final Debug
debug

This field is not null if -Djava.security.debug=securerandom is specified on the command line.

protected static final int
DEFAULT_STRENGTH

Default strength of a DRBG instance if it is not configured.

private static final EntropySource
defaultES

The default EntropySource determined by system property "java.security.egd" or security property "securerandom.source".

private EntropySource
es

The entropy source used by this instance.

protected int
highestSupportedSecurityStrength

highest_supported_security_strength of this mechanism for all algorithms it supports.

private boolean
instantiated

protected int
maxAdditionalInputLength

Maximum additional input length in bytes for this DRBG instance.

protected int
maxLength

Maximum entropy input length in bytes for this DRBG instance.

protected int
maxNumberOfBytesPerRequest

max_number_of_bits_per_request in bytes for this DRBG instance.

protected int
maxPersonalizationStringLength

Maximum personalization string length in bytes for this DRBG instance.

protected String
mechName

Mechanism name, say, HashDRBG.

protected int
minLength

Minimum entropy input length in bytes for this DRBG instance.

protected byte[]
nonce

The nonce for this instance.

protected byte[]
personalizationString

The personalization string used by this instance.

private boolean
predictionResistanceFlag

The prediction resistance flag used by this instance.

protected String
requestedAlgorithm

Requested algorithm in MoreDrbgParameters.

protected int
requestedInstantiationSecurityStrength

Strength requested in DrbgParameters.Instantiation.

private byte[]
requestedNonce

Requested nonce in MoreDrbgParameters.

protected volatile int
reseedCounter

Reseed counter of a DRBG instance.

protected int
reseedInterval

Maximum number of requests between reseeds for this DRBG instance.

protected int
securityStrength

Security strength for this instance.

protected boolean
supportPredictionResistance

Whether prediction resistance is supported.

protected boolean
supportReseeding

Whether reseed is supported.

protected boolean
usedf

Whether a derivation function is used.

Constructor Summary

AccessConstructor and Description
protected
AbstractDrbg()

A constructor without argument so that an implementation does not need to always write super(params).

protected
AbstractDrbg(SecureRandomParameters
the SecureRandomParameters object. This argument can be null.
params)

A mechanism shall override this constructor to set up mechName, highestSupportedSecurityStrength, supportPredictionResistance, supportReseeding or other features like DEFAULT_STRENGTH.

Method Summary

Modifier and TypeMethod and Description
protected abstract void
chooseAlgorithmAndStrength()

Decides what algorithm and strength to use (SHA-256 or AES-256, 128 or 256).

protected final void
configure(SecureRandomParameters
configuration, if null, default configuration (default strength, pr_false, no personalization string) is used.
params)

Configure this DRBG.

public final byte[]

Returns:

the seed bytes.
engineGenerateSeed(int
the number of seed bytes to generate.
numBytes)

Returns the given number of seed bytes.

protected SecureRandomParameters

Returns:

the current configuration
engineGetParameters()

Returns the current configuration as a DrbgParameters.Instantiation object.

protected final void
engineNextBytes(byte[] result)

protected final void
engineNextBytes(byte[] result, SecureRandomParameters params)

public final void
engineReseed(SecureRandomParameters params)

public final synchronized void
engineSetSeed(byte[]
the seed
input)

Reseeds this random object with the given seed.

protected abstract void
generateAlgorithm(byte[]
fill result here, not null
result, byte[]
additional input, can be null. If not null, its length is smaller than maxAdditionalInputLength
additionalInput)

The generate function.

private byte[]
getEntropyInput(boolean isPr)

private byte[]
getEntropyInput(int minEntropy, int minLength, int maxLength, boolean pr)

protected static int

Returns:

the standard strength
getStandardStrength(int
the input strength
input)

Returns the smallest standard strength (112, 128, 192, 256) that is greater or equal to the input.

protected abstract void
initEngine()

Initiates security engines (MessageDigest, Mac, or Cipher).

protected abstract void
instantiateAlgorithm(byte[]
the entropy input, its length is already conditioned to be between minLength and maxLength.
ei)

Instantiates a DRBG.

private synchronized void
instantiateIfNecessary(byte[]
a user-provided entropy, the length is already good. If null, will fetch entropy input automatically.
entropy)

Instantiate if necessary,

protected void
reseedAlgorithm(byte[]
the entropy input, its length is already conditioned to be between minLength and maxLength.
ei, byte[]
additional input, can be null. If not null, its length is smaller than maxAdditionalInputLength
additionalInput)

The reseed function.

public String
toString()

Overrides java.lang.Object.toString.

Returns a string representation of the object.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAllwaitwaitwait

Field Detail

algorithmback to summary
protected String algorithm

Algorithm used by this instance (SHA-512 or AES-256). Must be assigned in chooseAlgorithmAndStrength. This field is used in toString().

debugback to summary
protected static final Debug debug

This field is not null if -Djava.security.debug=securerandom is specified on the command line. An implementation can print useful debug info.

DEFAULT_STRENGTHback to summary
protected static final int DEFAULT_STRENGTH

Default strength of a DRBG instance if it is not configured. 128 is considered secure enough now. A mechanism can change it in a constructor. Remember to sync with "securerandom.drbg.config" in java.security.

defaultESback to summary
private static final EntropySource defaultES

The default EntropySource determined by system property "java.security.egd" or security property "securerandom.source".

This object uses SeedGenerator#generateSeed(byte[]) to return a byte array containing minLength bytes. It is assumed to support prediction resistance and always contains full-entropy.

esback to summary
private EntropySource es

The entropy source used by this instance. Set inside configure(SecureRandomParameters). This field can be null. getEntropyInput will take care of null check.

highestSupportedSecurityStrengthback to summary
protected int highestSupportedSecurityStrength

highest_supported_security_strength of this mechanism for all algorithms it supports. A mechanism should update the value in its constructor if the value is not 256.

instantiatedback to summary
private boolean instantiated
maxAdditionalInputLengthback to summary
protected int maxAdditionalInputLength

Maximum additional input length in bytes for this DRBG instance. Should be assigned in chooseAlgorithmAndStrength if it is not Integer#MAX_VALUE.

maxLengthback to summary
protected int maxLength

Maximum entropy input length in bytes for this DRBG instance. Should be assigned in chooseAlgorithmAndStrength if it is not Integer#MAX_VALUE.

In theory this value (and the values below) can be bigger than Integer.MAX_VALUE but a Java array can only have an int32 index.

maxNumberOfBytesPerRequestback to summary
protected int maxNumberOfBytesPerRequest

max_number_of_bits_per_request in bytes for this DRBG instance. Should be assigned in chooseAlgorithmAndStrength if it is not Integer#MAX_VALUE.

maxPersonalizationStringLengthback to summary
protected int maxPersonalizationStringLength

Maximum personalization string length in bytes for this DRBG instance. Should be assigned in chooseAlgorithmAndStrength if it is not Integer#MAX_VALUE.

mechNameback to summary
protected String mechName

Mechanism name, say, HashDRBG. Must be set in constructor. This value will be used in toString.

minLengthback to summary
protected int minLength

Minimum entropy input length in bytes for this DRBG instance. Must be assigned in chooseAlgorithmAndStrength.

nonceback to summary
protected byte[] nonce

The nonce for this instance. Set in instantiateIfNecessary. After instantiation, this field is not null. Do not modify it in a mechanism.

personalizationStringback to summary
protected byte[] personalizationString

The personalization string used by this instance. Set inside configure(SecureRandomParameters) and can be used in a mechanism. Do not modify it in a mechanism.

predictionResistanceFlagback to summary
private boolean predictionResistanceFlag

The prediction resistance flag used by this instance. Set inside configure(SecureRandomParameters).

requestedAlgorithmback to summary
protected String requestedAlgorithm

Requested algorithm in MoreDrbgParameters. Do not modify it in a mechanism.

requestedInstantiationSecurityStrengthback to summary
protected int requestedInstantiationSecurityStrength

Strength requested in DrbgParameters.Instantiation. The real strength is based on it. Do not modify it in a mechanism.

requestedNonceback to summary
private byte[] requestedNonce

Requested nonce in MoreDrbgParameters. If set to null, nonce will be chosen by system, and a reinstantiated DRBG will get a new system-provided nonce.

reseedCounterback to summary
protected volatile int reseedCounter

Reseed counter of a DRBG instance. A mechanism should increment it after each random bits generation and reset it in reseed. A mechanism does not need to compare it to reseedInterval. Volatile, will be used in double-checked locking.

reseedIntervalback to summary
protected int reseedInterval

Maximum number of requests between reseeds for this DRBG instance. Should be assigned in chooseAlgorithmAndStrength if it is not Integer#MAX_VALUE.

securityStrengthback to summary
protected int securityStrength

Security strength for this instance. Must be assigned in chooseAlgorithmAndStrength. Should be at least the requested strength. Might be smaller than the highest strength algorithm supports. Must not be -1.

supportPredictionResistanceback to summary
protected boolean supportPredictionResistance

Whether prediction resistance is supported. A mechanism should update the value in its constructor if it is not supported.

supportReseedingback to summary
protected boolean supportReseeding

Whether reseed is supported. A mechanism should update the value in its constructor if it is not supported.

usedfback to summary
protected boolean usedf

Whether a derivation function is used. Requested in MoreDrbgParameters. Only CtrDRBG uses it. Do not modify it in a mechanism.

Constructor Detail

AbstractDrbgback to summary
protected AbstractDrbg()

A constructor without argument so that an implementation does not need to always write super(params).

AbstractDrbgback to summary
protected AbstractDrbg(SecureRandomParameters params)

A mechanism shall override this constructor to set up mechName, highestSupportedSecurityStrength, supportPredictionResistance, supportReseeding or other features like DEFAULT_STRENGTH. Finally, it shall call configure on params.

Parameters
params:SecureRandomParameters

the SecureRandomParameters object. This argument can be null.

Exceptions
IllegalArgumentException:
if params is inappropriate for this SecureRandom.

Method Detail

chooseAlgorithmAndStrengthback to summary
protected abstract void chooseAlgorithmAndStrength()

Decides what algorithm and strength to use (SHA-256 or AES-256, 128 or 256). Strength related fields must also be defined or redefined here. Called in configure. A mechanism uses requestedAlgorithm, requestedInstantiationSecurityStrength, and DEFAULT_STRENGTH to decide which algorithm and strength to use.

If requestedAlgorithm is provided, it will always be used. If requestedInstantiationSecurityStrength is also provided, the algorithm will use the strength (an exception will be thrown if the strength is not supported), otherwise, the smaller one of the highest supported strength of the algorithm and the default strength will be used.

If requestedAlgorithm is not provided, an algorithm will be chosen that supports requestedInstantiationSecurityStrength (or DEFAULT_STRENGTH if there is no request).

Since every call to configure will call this method, make sure to the calls do not contradict with each other.

Here are some examples of the algorithm and strength chosen (suppose DEFAULT_STRENGTH is 128) for HashDRBG: 

requested             effective
(SHA-224, 256)        IAE
(SHA-256, -1)         (SHA-256,128)
(SHA-256, 112)        (SHA-256,112)
(SHA-256, 128)        (SHA-256,128)
(SHA-3, -1)           IAE
(null, -1)            (SHA-256,128)
(null, 112)           (SHA-256,112)
(null, 192)           (SHA-256,192)
(null, 256)           (SHA-256,256)
(null, 384)           IAE
Exceptions
IllegalArgumentException:
if the requested parameters can not be supported or contradict with each other.
configureback to summary
protected final void configure(SecureRandomParameters params)

Configure this DRBG. This method calls chooseAlgorithmAndStrength() and initEngine() but does not do the actual instantiation.

Parameters
params:SecureRandomParameters

configuration, if null, default configuration (default strength, pr_false, no personalization string) is used.

Exceptions
IllegalArgumentException:
if params is inappropriate for this SecureRandom.
engineGenerateSeedback to summary
public final byte[] engineGenerateSeed(int numBytes)

Returns the given number of seed bytes. A DRBG always uses SeedGenerator to get an array with full-entropy.

The implementation is identical to SHA1PRNG's SecureRandom#engineGenerateSeed.

Parameters
numBytes:int

the number of seed bytes to generate.

Returns:byte[]

the seed bytes.

engineGetParametersback to summary
protected SecureRandomParameters engineGetParameters()

Returns the current configuration as a DrbgParameters.Instantiation object.

Returns:SecureRandomParameters

the current configuration

engineNextBytesback to summary
protected final void engineNextBytes(byte[] result)
engineNextBytesback to summary
protected final void engineNextBytes(byte[] result, SecureRandomParameters params)
engineReseedback to summary
public final void engineReseed(SecureRandomParameters params)
engineSetSeedback to summary
public final synchronized void engineSetSeed(byte[] input)

Reseeds this random object with the given seed. A DRBG always expands or truncates the input to be between minLength and maxLength and uses it to instantiate or reseed itself (depending on whether the DRBG is instantiated).

Parameters
input:byte[]

the seed

generateAlgorithmback to summary
protected abstract void generateAlgorithm(byte[] result, byte[] additionalInput)

The generate function.

Parameters
result:byte[]

fill result here, not null

additionalInput:byte[]

additional input, can be null. If not null, its length is smaller than maxAdditionalInputLength

getEntropyInputback to summary
private byte[] getEntropyInput(boolean isPr)
getEntropyInputback to summary
private byte[] getEntropyInput(int minEntropy, int minLength, int maxLength, boolean pr)
getStandardStrengthback to summary
protected static int getStandardStrength(int input)

Returns the smallest standard strength (112, 128, 192, 256) that is greater or equal to the input.

Parameters
input:int

the input strength

Returns:int

the standard strength

initEngineback to summary
protected abstract void initEngine()

Initiates security engines (MessageDigest, Mac, or Cipher). This method is called during instantiation.

instantiateAlgorithmback to summary
protected abstract void instantiateAlgorithm(byte[] ei)

Instantiates a DRBG. Called automatically before the first nextBytes call.

Note that the other parameters (nonce, strength, ps) are already stored inside at configuration.

Parameters
ei:byte[]

the entropy input, its length is already conditioned to be between minLength and maxLength.

instantiateIfNecessaryback to summary
private synchronized void instantiateIfNecessary(byte[] entropy)

Instantiate if necessary,

Parameters
entropy:byte[]

a user-provided entropy, the length is already good. If null, will fetch entropy input automatically.

reseedAlgorithmback to summary
protected void reseedAlgorithm(byte[] ei, byte[] additionalInput)

The reseed function.

Parameters
ei:byte[]

the entropy input, its length is already conditioned to be between minLength and maxLength.

additionalInput:byte[]

additional input, can be null. If not null, its length is smaller than maxAdditionalInputLength

Exceptions
UnsupportedOperationException:
if reseed is not supported
toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object. Satisfying this method's contract implies a non-null result must be returned.

Annotations
@Override
sun.security.provider back to summary

private Class AbstractDrbg.NonceProvider

extends Object
Class Inheritance

Field Summary

Modifier and TypeField and Description
private static final byte[]
block

Constructor Summary

AccessConstructor and Description
private
NonceProvider()

Method Summary

Modifier and TypeMethod and Description
private static synchronized byte[]
next()

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

blockback to summary
private static final byte[] block

Constructor Detail

NonceProviderback to summary
private NonceProvider()

Method Detail

nextback to summary
private static synchronized byte[] next()
sun.security.provider back to summary

private Class AbstractDrbg.SeederHolder

extends Object
Class Inheritance

Field Summary

Modifier and TypeField and Description
pack-priv static final EntropySource
prseeder

Default EntropySource for SecureRandom with prediction resistance,

pack-priv static final EntropySource
seeder

Default EntropySource for SecureRandom without prediction resistance, which is backed by a DRBG whose EntropySource is prseeder.

Constructor Summary

AccessConstructor and Description
private
SeederHolder()

Method Summary

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

prseederback to summary
pack-priv static final EntropySource prseeder

Default EntropySource for SecureRandom with prediction resistance,

seederback to summary
pack-priv static final EntropySource seeder

Default EntropySource for SecureRandom without prediction resistance, which is backed by a DRBG whose EntropySource is prseeder.

Constructor Detail

SeederHolderback to summary
private SeederHolder()