Added in [API level 35](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) Summary: [Nested Classes](https://developer.android.com/reference/java/security/DrbgParameters#nestedclasses) \| [Methods](https://developer.android.com/reference/java/security/DrbgParameters#pubmethods) \| [Inherited Methods](https://developer.android.com/reference/java/security/DrbgParameters#inhmethods)
# DrbgParameters
` public class DrbgParameters `
` extends https://developer.android.com/reference/java/lang/Object ` ` `
|---|---|
| [java.lang.Object](https://developer.android.com/reference/java/lang/Object) ||
| ↳ | java.security.DrbgParameters |
*** ** * ** ***
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](http://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-90Ar1.pdf) (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:
- an entropy source,
- a DRBG mechanism (for example, Hash_DRBG),
- a DRBG algorithm (for example, SHA-256 for Hash_DRBG and AES-256 for CTR_DRBG. Please note that it is not the algorithm used in `https://developer.android.com/reference/java/security/SecureRandom#getInstance(java.lang.String)`, which we will call a *SecureRandom algorithm* below),
- optional features, including prediction resistance and reseeding supports,
- highest security strength.
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:
- required security strength,
- if prediction resistance is required,
- personalization string and additional input.
A DRBG instance can be instantiated with parameters from an `https://developer.android.com/reference/java/security/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 `https://developer.android.com/reference/java/security/DrbgParameters.Reseed` object. This maps to the `Reseed_function` defined in NIST SP 800-90Ar1. Calling `https://developer.android.com/reference/java/security/SecureRandom#reseed()` is equivalent to calling `https://developer.android.com/reference/java/security/SecureRandom#reseed(java.security.SecureRandomParameters)` with the effective instantiated prediction resistance flag (as returned by `https://developer.android.com/reference/java/security/SecureRandom#getParameters()`) with no additional input.
A DRBG instance generates data with additional parameters from a `https://developer.android.com/reference/java/security/DrbgParameters.NextBytes` object. This maps to the `Generate_function` defined in NIST SP 800-90Ar1. Calling `https://developer.android.com/reference/java/security/SecureRandom#nextBytes(byte[])` is equivalent to calling `https://developer.android.com/reference/java/security/SecureRandom#nextBytes(byte[],%20java.security.SecureRandomParameters)` with the effective instantiated strength and prediction resistance flag (as returned by `https://developer.android.com/reference/java/security/SecureRandom#getParameters()`) with no additional input.
A DRBG should be implemented as a subclass of `https://developer.android.com/reference/java/security/SecureRandomSpi`. It is recommended that the implementation contain the 1-arg [constructor](https://developer.android.com/reference/java/security/SecureRandomSpi#SecureRandomSpi(java.security.SecureRandomParameters)) 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 `https://developer.android.com/reference/java/security/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 `https://developer.android.com/reference/java/security/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 `https://developer.android.com/reference/java/security/DrbgParameters.Capability#NONE` but the effective value can be `https://developer.android.com/reference/java/security/DrbgParameters.Capability#RESEED_ONLY` if the implementation supports reseeding. The implementation must implement the `https://developer.android.com/reference/java/security/SecureRandomSpi#engineNextBytes(byte[],%20java.security.SecureRandomParameters)` method which takes a `DrbgParameters.NextBytes` parameter. Unless the result of `https://developer.android.com/reference/java/security/SecureRandom#getParameters()` has its [capability](https://developer.android.com/reference/java/security/DrbgParameters.Instantiation#getCapability()) being `https://developer.android.com/reference/java/security/DrbgParameters.Capability#NONE`, it must implement `https://developer.android.com/reference/java/security/SecureRandomSpi#engineReseed(java.security.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 `https://developer.android.com/reference/java/security/SecureRandom#getParameters()` must return `null`, and it does not need to implement either `https://developer.android.com/reference/java/security/SecureRandomSpi#engineNextBytes(byte[],%20java.security.SecureRandomParameters)` or `https://developer.android.com/reference/java/security/SecureRandomSpi#engineReseed(java.security.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()));
> ```
## Summary
| ### Nested classes ||
|---|---|
| ` class` | `https://developer.android.com/reference/java/security/DrbgParameters.Instantiation` DRBG parameters for instantiation. |
| ` class` | `https://developer.android.com/reference/java/security/DrbgParameters.NextBytes` DRBG parameters for random bits generation. |
| ` class` | `https://developer.android.com/reference/java/security/DrbgParameters.Reseed` DRBG parameters for reseed. |
| ### Public methods ||
|---|---|
| ` static https://developer.android.com/reference/java/security/DrbgParameters.Instantiation` | ` https://developer.android.com/reference/java/security/DrbgParameters#instantiation(int,%20java.security.DrbgParameters.Capability,%20byte[])(int strength, https://developer.android.com/reference/java/security/DrbgParameters.Capability capability, byte[] personalizationString) ` Generates a `https://developer.android.com/reference/java/security/DrbgParameters.Instantiation` object. |
| ` static https://developer.android.com/reference/java/security/DrbgParameters.NextBytes` | ` https://developer.android.com/reference/java/security/DrbgParameters#nextBytes(int,%20boolean,%20byte[])(int strength, boolean predictionResistance, byte[] additionalInput) ` Generates a `https://developer.android.com/reference/java/security/DrbgParameters.NextBytes` object. |
| ` static https://developer.android.com/reference/java/security/DrbgParameters.Reseed` | ` https://developer.android.com/reference/java/security/DrbgParameters#reseed(boolean,%20byte[])(boolean predictionResistance, byte[] additionalInput) ` Generates a `https://developer.android.com/reference/java/security/DrbgParameters.Reseed` object. |
### Inherited methods
From class ` https://developer.android.com/reference/java/lang/Object ` ` https://developer.android.com/reference/java/lang/Object` ` https://developer.android.com/reference/java/lang/Object#clone()() `
Creates and returns a copy of this object.
` boolean` ` https://developer.android.com/reference/java/lang/Object#equals(java.lang.Object)(https://developer.android.com/reference/java/lang/Object obj) `
Indicates whether some other object is "equal to" this one.
` void` ` https://developer.android.com/reference/java/lang/Object#finalize()() `
Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
` final https://developer.android.com/reference/java/lang/Class` ` https://developer.android.com/reference/java/lang/Object#getClass()() `
Returns the runtime class of this `Object`.
` int` ` https://developer.android.com/reference/java/lang/Object#hashCode()() `
Returns a hash code value for the object.
` final void` ` https://developer.android.com/reference/java/lang/Object#notify()() `
Wakes up a single thread that is waiting on this object's monitor.
` final void` ` https://developer.android.com/reference/java/lang/Object#notifyAll()() `
Wakes up all threads that are waiting on this object's monitor.
` https://developer.android.com/reference/java/lang/String` ` https://developer.android.com/reference/java/lang/Object#toString()() `
Returns a string representation of the object.
` final void` ` https://developer.android.com/reference/java/lang/Object#wait(long,%20int)(long timeoutMillis, int nanos) `
Causes the current thread to wait until it is awakened, typically by being *notified* or *interrupted*, or until a certain amount of real time has elapsed.
` final void` ` https://developer.android.com/reference/java/lang/Object#wait(long)(long timeoutMillis) `
Causes the current thread to wait until it is awakened, typically by being *notified* or *interrupted*, or until a certain amount of real time has elapsed.
` final void` ` https://developer.android.com/reference/java/lang/Object#wait()() `
Causes the current thread to wait until it is awakened, typically by being *notified* or *interrupted*.
## Public methods
### instantiation
Added in [API level 35](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public static DrbgParameters.Instantiation instantiation (int strength,
DrbgParameters.Capability capability,
byte[] personalizationString)
```
Generates a `https://developer.android.com/reference/java/security/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 ||
|---|---|
| `https://developer.android.com/reference/java/security/DrbgParameters.Instantiation` | a new `Instantiation` object
|
| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException` | if `strength` is less than -1 |
| `https://developer.android.com/reference/java/lang/NullPointerException` | if `capability` is `null` |
### nextBytes
Added in [API level 35](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public static DrbgParameters.NextBytes nextBytes (int strength,
boolean predictionResistance,
byte[] additionalInput)
```
Generates a `https://developer.android.com/reference/java/security/DrbgParameters.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 ||
|---|---|
| `https://developer.android.com/reference/java/security/DrbgParameters.NextBytes` | a new `NextBytes` object
|
| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException` | if `strength` is less than -1 |
### reseed
Added in [API level 35](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public static DrbgParameters.Reseed reseed (boolean predictionResistance,
byte[] additionalInput)
```
Generates a `https://developer.android.com/reference/java/security/DrbgParameters.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 ||
|---|---|
| `https://developer.android.com/reference/java/security/DrbgParameters.Reseed` | a new `Reseed` object
|