According to NIST Special Publication 800-90A Revision 1, Recommendation for Random Number Generation Using Deterministic Random Bit Generators (800-90Ar1),
A DRBG is based on a DRBG mechanism as specified in this Recommendation and includes a source of randomness. A DRBG mechanism uses an algorithm (i.e., a DRBG algorithm) that produces a sequence of bits from an initial value that is determined by a seed that is determined from the output of the randomness source."
The 800-90Ar1 specification allows for a variety of DRBG implementation choices, such as:
SecureRandom#getInstance
, which we will call a
SecureRandom algorithm below),
These choices are set in each implementation and are not directly
managed by the SecureRandom
API. Check your DRBG provider's
documentation to find an appropriate implementation for the situation.
On the other hand, the 800-90Ar1 specification does have some configurable options, such as:
A DRBG instance can be instantiated with parameters from an
DrbgParameters.
object and other information
(for example, the nonce, which is not managed by this API). This maps
to the Instantiate_function
defined in NIST SP 800-90Ar1.
A DRBG instance can be reseeded with parameters from a
DrbgParameters.
object. This maps to the
Reseed_function
defined in NIST SP 800-90Ar1. Calling
SecureRandom#reseed()
is equivalent to calling
SecureRandom#reseed(SecureRandomParameters)
with the effective
instantiated prediction resistance flag (as returned by
SecureRandom#getParameters()
) with no additional input.
A DRBG instance generates data with additional parameters from a
DrbgParameters.
object. This maps to the
Generate_function
defined in NIST SP 800-90Ar1. Calling
SecureRandom#nextBytes(byte[])
is equivalent to calling
SecureRandom#nextBytes(byte[], SecureRandomParameters)
with the effective instantiated strength and prediction resistance flag
(as returned by SecureRandom#getParameters()
) with no
additional input.
A DRBG should be implemented as a subclass of SecureRandomSpi
.
It is recommended that the implementation contain the 1-arg
constructor
that takes a DrbgParameters.Instantiation
argument. If implemented
this way, this implementation can be chosen by any
SecureRandom.getInstance()
method. If it is chosen by a
SecureRandom.getInstance()
with a SecureRandomParameters
parameter, the parameter is passed into this constructor. If it is chosen
by a SecureRandom.getInstance()
without a
SecureRandomParameters
parameter, the constructor is called with
a null
argument and the implementation should choose its own
parameters. Its SecureRandom#getParameters()
must always return a
non-null effective DrbgParameters.Instantiation
object that reflects
how the DRBG is actually instantiated. A caller can use this information
to determine whether a SecureRandom
object is a DRBG and what
features it supports. Please note that the returned value does not
necessarily equal to the DrbgParameters.Instantiation
object passed
into the SecureRandom.getInstance()
call. For example,
the requested capability can be DrbgParameters.
but the effective value can be DrbgParameters.
if the implementation supports reseeding. The implementation must implement
the SecureRandomSpi#engineNextBytes(byte[], SecureRandomParameters)
method which takes a DrbgParameters.NextBytes
parameter. Unless
the result of SecureRandom#getParameters()
has its
capability being
NONE
, it must implement
SecureRandomSpi#engineReseed(SecureRandomParameters)
which takes
a DrbgParameters.Reseed
parameter.
On the other hand, if a DRBG implementation does not contain a constructor
that has an DrbgParameters.Instantiation
argument (not recommended),
it can only be chosen by a SecureRandom.getInstance()
without
a SecureRandomParameters
parameter, but will not be chosen if
a getInstance
method with a SecureRandomParameters
parameter
is called. If implemented this way, its SecureRandom#getParameters()
must return null
, and it does not need to implement either
SecureRandomSpi#engineNextBytes(byte[], SecureRandomParameters)
or SecureRandomSpi#engineReseed(SecureRandomParameters)
.
A DRBG might reseed itself automatically if the seed period is bigger than the maximum seed life defined by the DRBG mechanism.
A DRBG implementation should support serialization and deserialization by retaining the configuration and effective parameters, but the internal state must not be serialized and the deserialized object must be reinstantiated.
Examples:
SecureRandom drbg; byte[] buffer = new byte[32]; // Any DRBG is OK drbg = SecureRandom.getInstance("DRBG"); drbg.nextBytes(buffer); SecureRandomParameters params = drbg.getParameters(); if (params instanceof DrbgParameters.Instantiation) { DrbgParameters.Instantiation ins = (DrbgParameters.Instantiation) params; if (ins.getCapability().supportsReseeding()) { drbg.reseed(); } } // The following call requests a weak DRBG instance. It is only // guaranteed to support 112 bits of security strength. drbg = SecureRandom.getInstance("DRBG", DrbgParameters.instantiation(112, NONE, null)); // Both the next two calls will likely fail, because drbg could be // instantiated with a smaller strength with no prediction resistance // support. drbg.nextBytes(buffer, DrbgParameters.nextBytes(256, false, "more".getBytes())); drbg.nextBytes(buffer, DrbgParameters.nextBytes(112, true, "more".getBytes())); // The following call requests a strong DRBG instance, with a // personalization string. If it successfully returns an instance, // that instance is guaranteed to support 256 bits of security strength // with prediction resistance available. drbg = SecureRandom.getInstance("DRBG", DrbgParameters.instantiation( 256, PR_AND_RESEED, "hello".getBytes())); // Prediction resistance is not requested in this single call, // but an additional input is used. drbg.nextBytes(buffer, DrbgParameters.nextBytes(-1, false, "more".getBytes())); // Same for this call. drbg.reseed(DrbgParameters.reseed(false, "extra".getBytes()));
Implementation Specification
By convention, a provider should name its primary DRBG implementation
with the
standard SecureRandom
algorithm name "DRBG".
Implementation Note
The following notes apply to the "DRBG" implementation in the SUN provider of the JDK reference implementation.
This implementation supports the Hash_DRBG and HMAC_DRBG mechanisms with DRBG algorithm SHA-224, SHA-512/224, SHA-256, SHA-512/256, SHA-384 and SHA-512, and CTR_DRBG (both using derivation function and not using derivation function) with DRBG algorithm AES-128, AES-192 and AES-256.
The mechanism name and DRBG algorithm name are determined by the
security property
securerandom.drbg.config
. The default choice is Hash_DRBG
with SHA-256.
For each combination, the security strength can be requested from 112 up to the highest strength it supports. Both reseeding and prediction resistance are supported.
Personalization string is supported through the
DrbgParameters.
class and additional input is supported
through the DrbgParameters.
and
DrbgParameters.
classes.
If a DRBG is not instantiated with a DrbgParameters.
object explicitly, this implementation instantiates it with a default
requested strength of 128 bits, no prediction resistance request, and
no personalization string. These default instantiation parameters can also
be customized with the securerandom.drbg.config
security property.
This implementation reads fresh entropy from the system default entropy
source determined by the security property securerandom.source
.
Calling SecureRandom#generateSeed(int)
will directly read
from this system default entropy source.
Modifier and Type | Class and Description |
---|---|
public static enum | DrbgParameters.
The reseedable and prediction resistance capabilities of a DRBG. |
public static class | DrbgParameters.
DRBG parameters for instantiation. |
public static class | DrbgParameters.
DRBG parameters for random bits generation. |
public static class | DrbgParameters.
DRBG parameters for reseed. |
Access | Constructor and Description |
---|---|
private |
Modifier and Type | Method and Description |
---|---|
public static DrbgParameters. | Returns: a newInstantiation objectsecurity strength in bits, -1 for default strength
if used in strength, DrbgParameters.getInstance .capability capability,personalization string as a byte array,
can be personalizationString)null . The content of this
byte array will be copied.Generates a |
public static DrbgParameters. | Returns: a newNextBytes objectrequested security strength in bits. If set to -1, the
effective strength will be used. strength, boolean prediction resistance requested predictionResistance, byte[] additional input, can be additionalInput)null .
The content of this byte array will be copied.Generates a |
public static DrbgParameters. |
DrbgParameters | back to summary |
---|---|
private DrbgParameters() |
instantiation | back to summary |
---|---|
public static DrbgParameters. Generates a
|
nextBytes | back to summary |
---|---|
public static DrbgParameters. Generates a
|
reseed | back to summary |
---|---|
public static DrbgParameters. Generates a
|
When this object is passed to a SecureRandom.getInstance()
call,
it is the requested minimum capability. When it's returned from
SecureRandom.getParameters()
, it is the effective capability.
Please note that while the Instantiate_function
defined in
NIST SP 800-90Ar1 only includes a prediction_resistance_flag
parameter, the Capability
type includes an extra value
RESEED_ONLY
because reseeding is an optional function.
If NONE
is used in an Instantiation
object in calling the
SecureRandom.getInstance
method, the returned DRBG instance
is not guaranteed to support reseeding. If RESEED_ONLY
or
PR_AND_RESEED
is used, the instance must support reseeding.
The table below lists possible effective values if a certain capability is requested, i.e.
Capability requested = ...; SecureRandom s = SecureRandom.getInstance("DRBG", DrbgParameters(-1, requested, null)); Capability effective = ((DrbgParametes.Initiate) s.getParameters()) .getCapability();
Requested Value | Possible Effective Values |
---|---|
NONE | NONE, RESEED_ONLY, PR_AND_RESEED |
RESEED_ONLY | RESEED_ONLY, PR_AND_RESEED |
PR_AND_RESEED | PR_AND_RESEED |
A DRBG implementation supporting prediction resistance must also support reseeding.
Modifier and Type | Field and Description |
---|---|
public static final DrbgParameters. | NONE
Neither prediction resistance nor reseed. |
public static final DrbgParameters. | PR_AND_RESEED
Both prediction resistance and reseed. |
public static final DrbgParameters. | RESEED_ONLY
Reseed but no prediction resistance. |
Access | Constructor and Description |
---|---|
private |
Modifier and Type | Method and Description |
---|---|
public boolean | |
public boolean | |
public String | toString()
Overrides java. Returns the name of this enum constant, as contained in the declaration. |
public static DrbgParameters. | |
public static DrbgParameters. |
NONE | back to summary |
---|---|
public static final DrbgParameters. Neither prediction resistance nor reseed. |
PR_AND_RESEED | back to summary |
---|---|
public static final DrbgParameters. Both prediction resistance and reseed. |
RESEED_ONLY | back to summary |
---|---|
public static final DrbgParameters. Reseed but no prediction resistance. |
Capability | back to summary |
---|---|
private Capability() |
supportsPredictionResistance | back to summary |
---|---|
public boolean supportsPredictionResistance() Returns whether this capability supports prediction resistance.
|
supportsReseeding | back to summary |
---|---|
public boolean supportsReseeding() Returns whether this capability supports reseeding.
|
toString | back to summary |
---|---|
public String toString() Overrides java. Doc from java. Returns the name of this enum constant, as contained in the declaration. This method may be overridden, though it typically isn't necessary or desirable. An enum class should override this method when a more "programmer-friendly" string form exists. |
valueOf | back to summary |
---|---|
public static DrbgParameters. |
values | back to summary |
---|---|
public static DrbgParameters. |
When used in
SecureRandom#getInstance(String, SecureRandomParameters)
or one of the other similar getInstance
calls that take a
SecureRandomParameters
parameter, it means the
requested instantiate parameters the newly created SecureRandom
object must minimally support. When used as the return value of the
SecureRandom#getParameters()
method, it means the effective
instantiate parameters of the SecureRandom
object.
Modifier and Type | Field and Description |
---|---|
private final DrbgParameters. | |
private final byte[] | |
private final int |
Access | Constructor and Description |
---|---|
private |
Modifier and Type | Method and Description |
---|---|
public DrbgParameters. | Returns: If used ingetInstance , returns the minimum
capability requested. If used in getParameters , returns
information on the effective prediction resistance flag and
whether it supports reseeding.Returns the capability. |
public byte[] | Returns: If used ingetInstance , returns the requested
personalization string as a newly allocated array, or null
if no personalization string is requested. The same string should
be returned in getParameters as a new copy, or null
if no personalization string is requested in getInstance .Returns the personalization string as a byte array. |
public int | Returns: If used ingetInstance , returns the minimum strength
requested, or -1 if there is no specific request on the strength.
If used in getParameters , returns the effective strength.
The effective strength must be greater than or equal to the minimum
strength requested.Returns the security strength in bits. |
public String | Returns: the string representationOverrides java. Returns a Human-readable string representation of this
|
capability | back to summary |
---|---|
private final DrbgParameters. |
personalizationString | back to summary |
---|---|
private final byte[] personalizationString |
strength | back to summary |
---|---|
private final int strength |
Instantiation | back to summary |
---|---|
private Instantiation(int strength, DrbgParameters. |
getCapability | back to summary |
---|---|
public DrbgParameters. Returns the capability.
|
getPersonalizationString | back to summary |
---|---|
public byte[] getPersonalizationString() Returns the personalization string as a byte array.
|
getStrength | back to summary |
---|---|
public int getStrength() Returns the security strength in bits.
|
toString | back to summary |
---|---|
public String toString() Overrides java. Returns a Human-readable string representation of this
|
SecureRandom#nextBytes(byte[], SecureRandomParameters)
.
Modifier and Type | Field and Description |
---|---|
private final byte[] | |
private final boolean | |
private final int |
Access | Constructor and Description |
---|---|
private |
Modifier and Type | Method and Description |
---|---|
public byte[] | Returns: the requested additional input,null if not
requested. A new byte array is returned each time this method
is called.Returns the requested additional input. |
public boolean | Returns: whether prediction resistance is requestedReturns whether prediction resistance is requested. |
public int | Returns: the strength requested, or -1 if the effective strength should be used.Returns the security strength requested in bits. |
additionalInput | back to summary |
---|---|
private final byte[] additionalInput |
predictionResistance | back to summary |
---|---|
private final boolean predictionResistance |
strength | back to summary |
---|---|
private final int strength |
NextBytes | back to summary |
---|---|
private NextBytes(int strength, boolean predictionResistance, byte[] additionalInput) |
getAdditionalInput | back to summary |
---|---|
public byte[] getAdditionalInput() Returns the requested additional input.
|
getPredictionResistance | back to summary |
---|---|
public boolean getPredictionResistance() Returns whether prediction resistance is requested.
|
getStrength | back to summary |
---|---|
public int getStrength() Returns the security strength requested in bits.
|
SecureRandom#reseed(SecureRandomParameters)
.
Modifier and Type | Field and Description |
---|---|
private final byte[] | |
private final boolean |
Access | Constructor and Description |
---|---|
private |
Modifier and Type | Method and Description |
---|---|
public byte[] | Returns: the requested additional input, ornull if
not requested. A new byte array is returned each time this method
is called.Returns the requested additional input. |
public boolean | Returns: whether prediction resistance is requestedReturns whether prediction resistance is requested. |
additionalInput | back to summary |
---|---|
private final byte[] additionalInput |
predictionResistance | back to summary |
---|---|
private final boolean predictionResistance |
Reseed | back to summary |
---|---|
private Reseed(boolean predictionResistance, byte[] additionalInput) |
getAdditionalInput | back to summary |
---|---|
public byte[] getAdditionalInput() Returns the requested additional input.
|
getPredictionResistance | back to summary |
---|---|
public boolean getPredictionResistance() Returns whether prediction resistance is requested.
|