Top Description Inners Constructors Methods
java.security

public Class DrbgParameters

extends Object
Class Inheritance
Imports
java.util.Arrays, .Locale, .Objects

This class specifies the parameters used by a DRBG (Deterministic Random Bit Generator).

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:

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.Instantiation 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.Reseed 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.NextBytes 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.Capability#NONE but the effective value can be DrbgParameters.Capability#RESEED_ONLY 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.Instantiation class and additional input is supported through the DrbgParameters.NextBytes and DrbgParameters.Reseed classes.

If a DRBG is not instantiated with a DrbgParameters.Instantiation 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.

Since
9

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static enum
DrbgParameters.Capability

The reseedable and prediction resistance capabilities of a DRBG.

public static class
DrbgParameters.Instantiation

DRBG parameters for instantiation.

public static class
DrbgParameters.NextBytes

DRBG parameters for random bits generation.

public static class
DrbgParameters.Reseed

DRBG parameters for reseed.

Constructor Summary

AccessConstructor and Description
private

Method Summary

Modifier and TypeMethod and Description
public static DrbgParameters.Instantiation

Returns:

a new Instantiation object
instantiation
(int
security strength in bits, -1 for default strength if used in getInstance.
strength
,
DrbgParameters.Capability
capability
capability
,
byte[]
personalization string as a byte array, can be null. The content of this byte array will be copied.
personalizationString
)

Generates a DrbgParameters.Instantiation object.

public static DrbgParameters.NextBytes

Returns:

a new NextBytes object
nextBytes
(int
requested 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 null. The content of this byte array will be copied.
additionalInput
)

Generates a NextBytes object.

public static DrbgParameters.Reseed

Returns:

a new Reseed object
reseed
(boolean
prediction resistance requested
predictionResistance
,
byte[]
additional input, can be null. The content of this byte array will be copied.
additionalInput
)

Generates a Reseed object.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Constructor Detail

DrbgParametersback to summary
private DrbgParameters()

Method Detail

instantiationback to summary
public static DrbgParameters.Instantiation instantiation(int strength, DrbgParameters.Capability capability, byte[] personalizationString)

Generates a DrbgParameters.Instantiation object.

Parameters
strength:int

security strength in bits, -1 for default strength if used in getInstance.

capability:DrbgParameters.Capability

capability

personalizationString:byte[]

personalization string as a byte array, can be null. The content of this byte array will be copied.

Returns:DrbgParameters.Instantiation

a new Instantiation object

Exceptions
NullPointerException:
if capability is null
IllegalArgumentException:
if strength is less than -1
nextBytesback to summary
public static DrbgParameters.NextBytes nextBytes(int strength, boolean predictionResistance, byte[] additionalInput)

Generates a NextBytes object.

Parameters
strength:int

requested security strength in bits. If set to -1, the effective strength will be used.

predictionResistance:boolean

prediction resistance requested

additionalInput:byte[]

additional input, can be null. The content of this byte array will be copied.

Returns:DrbgParameters.NextBytes

a new NextBytes object

Exceptions
IllegalArgumentException:
if strength is less than -1
reseedback to summary
public static DrbgParameters.Reseed reseed(boolean predictionResistance, byte[] additionalInput)

Generates a Reseed object.

Parameters
predictionResistance:boolean

prediction resistance requested

additionalInput:byte[]

additional input, can be null. The content of this byte array will be copied.

Returns:DrbgParameters.Reseed

a new Reseed object

java.security back to summary

public final Enum DrbgParameters.Capability

extends Enum<DrbgParameters.Capability>
Class Inheritance

The reseedable and prediction resistance capabilities of a DRBG.

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 and effective capabilities
Requested Value Possible Effective Values
NONENONE, RESEED_ONLY, PR_AND_RESEED
RESEED_ONLYRESEED_ONLY, PR_AND_RESEED
PR_AND_RESEEDPR_AND_RESEED

A DRBG implementation supporting prediction resistance must also support reseeding.

Since
9

Field Summary

Modifier and TypeField and Description
public static final DrbgParameters.Capability
NONE

Neither prediction resistance nor reseed.

public static final DrbgParameters.Capability
PR_AND_RESEED

Both prediction resistance and reseed.

public static final DrbgParameters.Capability
RESEED_ONLY

Reseed but no prediction resistance.

Constructor Summary

AccessConstructor and Description
private

Method Summary

Modifier and TypeMethod and Description
public boolean

Returns:

true for PR_AND_RESEED, and false for RESEED_ONLY and NONE
supportsPredictionResistance
()

Returns whether this capability supports prediction resistance.

public boolean

Returns:

true for PR_AND_RESEED and RESEED_ONLY, and false for NONE
supportsReseeding
()

Returns whether this capability supports reseeding.

public String
toString()

Overrides java.lang.Enum.toString.

Returns the name of this enum constant, as contained in the declaration.

public static DrbgParameters.Capability
public static DrbgParameters.Capability[]
Inherited from java.lang.Enum:
clonecompareTodescribeConstableequalsfinalizegetDeclaringClasshashCodenameordinalvalueOf

Field Detail

NONEback to summary
public static final DrbgParameters.Capability NONE

Neither prediction resistance nor reseed.

PR_AND_RESEEDback to summary
public static final DrbgParameters.Capability PR_AND_RESEED

Both prediction resistance and reseed.

RESEED_ONLYback to summary
public static final DrbgParameters.Capability RESEED_ONLY

Reseed but no prediction resistance.

Constructor Detail

Capabilityback to summary
private Capability()

Method Detail

supportsPredictionResistanceback to summary
public boolean supportsPredictionResistance()

Returns whether this capability supports prediction resistance.

Returns:boolean

true for PR_AND_RESEED, and false for RESEED_ONLY and NONE

supportsReseedingback to summary
public boolean supportsReseeding()

Returns whether this capability supports reseeding.

Returns:boolean

true for PR_AND_RESEED and RESEED_ONLY, and false for NONE

toStringback to summary
public String toString()

Overrides java.lang.Enum.toString.

Doc from java.lang.Enum.toString.

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.

Returns:String

the name of this enum constant

Annotations
@Override
valueOfback to summary
public static DrbgParameters.Capability valueOf(String name)
valuesback to summary
public static DrbgParameters.Capability[] values()
java.security back to summary

public final Class DrbgParameters.Instantiation

extends Object
implements SecureRandomParameters
Class Inheritance
All Implemented Interfaces
java.security.SecureRandomParameters

DRBG parameters for instantiation.

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.

Since
9

Field Summary

Modifier and TypeField and Description
private final DrbgParameters.Capability
private final byte[]
private final int

Constructor Summary

AccessConstructor and Description
private
Instantiation(int strength, DrbgParameters.Capability capability, byte[] personalizationString)

Method Summary

Modifier and TypeMethod and Description
public DrbgParameters.Capability

Returns:

If used in getInstance, returns the minimum capability requested. If used in getParameters, returns information on the effective prediction resistance flag and whether it supports reseeding.
getCapability
()

Returns the capability.

public byte[]

Returns:

If used in getInstance, 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.
getPersonalizationString
()

Returns the personalization string as a byte array.

public int

Returns:

If used in getInstance, 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.
getStrength
()

Returns the security strength in bits.

public String

Returns:

the string representation
toString
()

Overrides java.lang.Object.toString.

Returns a Human-readable string representation of this Instantiation.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAllwaitwaitwait

Field Detail

capabilityback to summary
private final DrbgParameters.Capability capability
personalizationStringback to summary
private final byte[] personalizationString
strengthback to summary
private final int strength

Constructor Detail

Instantiationback to summary
private Instantiation(int strength, DrbgParameters.Capability capability, byte[] personalizationString)

Method Detail

getCapabilityback to summary
public DrbgParameters.Capability getCapability()

Returns the capability.

Returns:DrbgParameters.Capability

If used in getInstance, returns the minimum capability requested. If used in getParameters, returns information on the effective prediction resistance flag and whether it supports reseeding.

getPersonalizationStringback to summary
public byte[] getPersonalizationString()

Returns the personalization string as a byte array.

Returns:byte[]

If used in getInstance, 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.

getStrengthback to summary
public int getStrength()

Returns the security strength in bits.

Returns:int

If used in getInstance, 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.

toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Returns a Human-readable string representation of this Instantiation.

Returns:String

the string representation

Annotations
@Override
java.security back to summary

public final Class DrbgParameters.NextBytes

extends Object
implements SecureRandomParameters
Class Inheritance
All Implemented Interfaces
java.security.SecureRandomParameters

DRBG parameters for random bits generation. It is used in SecureRandom#nextBytes(byte[], SecureRandomParameters).
Since
9

Field Summary

Modifier and TypeField and Description
private final byte[]
private final boolean
private final int

Constructor Summary

AccessConstructor and Description
private
NextBytes(int strength, boolean predictionResistance, byte[] additionalInput)

Method Summary

Modifier and TypeMethod 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.
getAdditionalInput
()

Returns the requested additional input.

public boolean

Returns:

whether prediction resistance is requested
getPredictionResistance
()

Returns whether prediction resistance is requested.

public int

Returns:

the strength requested, or -1 if the effective strength should be used.
getStrength
()

Returns the security strength requested in bits.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

additionalInputback to summary
private final byte[] additionalInput
predictionResistanceback to summary
private final boolean predictionResistance
strengthback to summary
private final int strength

Constructor Detail

NextBytesback to summary
private NextBytes(int strength, boolean predictionResistance, byte[] additionalInput)

Method Detail

getAdditionalInputback to summary
public byte[] getAdditionalInput()

Returns the requested additional input.

Returns:byte[]

the requested additional input, null if not requested. A new byte array is returned each time this method is called.

getPredictionResistanceback to summary
public boolean getPredictionResistance()

Returns whether prediction resistance is requested.

Returns:boolean

whether prediction resistance is requested

getStrengthback to summary
public int getStrength()

Returns the security strength requested in bits.

Returns:int

the strength requested, or -1 if the effective strength should be used.

java.security back to summary

public final Class DrbgParameters.Reseed

extends Object
implements SecureRandomParameters
Class Inheritance
All Implemented Interfaces
java.security.SecureRandomParameters

DRBG parameters for reseed. It is used in SecureRandom#reseed(SecureRandomParameters).
Since
9

Field Summary

Modifier and TypeField and Description
private final byte[]
private final boolean

Constructor Summary

AccessConstructor and Description
private
Reseed(boolean predictionResistance, byte[] additionalInput)

Method Summary

Modifier and TypeMethod and Description
public byte[]

Returns:

the requested additional input, or null if not requested. A new byte array is returned each time this method is called.
getAdditionalInput
()

Returns the requested additional input.

public boolean

Returns:

whether prediction resistance is requested
getPredictionResistance
()

Returns whether prediction resistance is requested.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

additionalInputback to summary
private final byte[] additionalInput
predictionResistanceback to summary
private final boolean predictionResistance

Constructor Detail

Reseedback to summary
private Reseed(boolean predictionResistance, byte[] additionalInput)

Method Detail

getAdditionalInputback to summary
public byte[] getAdditionalInput()

Returns the requested additional input.

Returns:byte[]

the requested additional input, or null if not requested. A new byte array is returned each time this method is called.

getPredictionResistanceback to summary
public boolean getPredictionResistance()

Returns whether prediction resistance is requested.

Returns:boolean

whether prediction resistance is requested