org.bouncycastle.crypto.prng
Class SP800SecureRandomBuilder

java.lang.Object
  org.bouncycastle.crypto.prng.SP800SecureRandomBuilder

public class SP800SecureRandomBuilder

extends java.lang.Object

Builder class for making SecureRandom objects based on SP 800-90A Deterministic Random Bit Generators (DRBG).

A typical use, building a SecureRandom on a Hash DRBG at the default 256-bit security strength:

SecureRandom entropySource = new SecureRandom(); // SP 800-90A sec. 8.6.7: at least (security strength / 2) bits of entropy, or a value that does not repeat byte[] nonce = new byte[16]; entropySource.nextBytes(nonce); SecureRandom random = new SP800SecureRandomBuilder(entropySource, false) .setPersonalizationString(Strings.toByteArray("example application, instance 1")) .buildHash(new SHA512Digest(), nonce, false);

An HMAC DRBG is built the same way with buildHMAC(new HMac(new SHA512Digest()), nonce, false), and a CTR DRBG with buildCTR(AESEngine.newInstance(), 256, nonce, false).

For full SP 800-90A compliance a nonce is required for all three: the Hash and HMAC DRBGs, and the CTR DRBG, which always uses the derivation function. As above, the nonce may be taken from the same source, and at the same time, as the entropy input; it may also be a value guaranteed not to repeat, such as a counter or a timestamp (SP 800-90A Rev. 1 sec. 8.6.7). Alternatively the nonce may be null if each entropy request supplies at least 1.5 times the security strength in entropy, which setEntropyBitsRequired(int) configures: the nonce's entropy then arrives as part of the entropy input (SP 800-90A Rev. 1 sec. 8.6.7 and 9.1). The personalization string is optional but recommended: something that distinguishes this instantiation, such as an application and instance name. Setting predictionResistant to true reseeds from the entropy source on every request for bytes, at the cost of reading entropy each time.

Constructor Summary

SP800SecureRandomBuilder()
Basic constructor, creates a builder using an EntropySourceProvider based on the default SecureRandom with predictionResistant set to false.

SP800SecureRandomBuilder(EntropySourceProvider entropySourceProvider)
Create a builder which makes creates the SecureRandom objects from a specified entropy source provider.

SP800SecureRandomBuilder(java.security.SecureRandom entropySource, boolean predictionResistant)
Construct a builder with an EntropySourceProvider based on the passed in SecureRandom and the passed in value for prediction resistance.

Method Summary

SP800SecureRandom	buildCTR(BlockCipher cipher, int keySizeInBits, byte[] nonce, boolean predictionResistant) Build a SecureRandom based on a SP 800-90A CTR DRBG.
SP800SecureRandom	buildHash(Digest digest, byte[] nonce, boolean predictionResistant) Build a SecureRandom based on a SP 800-90A Hash DRBG.
SP800SecureRandom	buildHMAC(Mac hMac, byte[] nonce, boolean predictionResistant) Build a SecureRandom based on a SP 800-90A HMAC DRBG.
SP800SecureRandomBuilder	setEntropyBitsRequired(int entropyBitsRequired) Set the amount of entropy bits required for seeding and reseeding DRBGs used in building SecureRandom objects.
SP800SecureRandomBuilder	setPersonalizationString(byte[] personalizationString) Set the personalization string for DRBG SecureRandoms created by this builder
SP800SecureRandomBuilder	setSecurityStrength(int securityStrength) Set the security strength required for DRBGs used in building SecureRandom objects.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SP800SecureRandomBuilder

public SP800SecureRandomBuilder()

Basic constructor, creates a builder using an EntropySourceProvider based on the default SecureRandom with predictionResistant set to false.

Any SecureRandom created from a builder constructed like this will make use of input passed to SecureRandom.setSeed() if the default SecureRandom does for its generateSeed() call.

SP800SecureRandomBuilder

public SP800SecureRandomBuilder(java.security.SecureRandom entropySource,
                                boolean predictionResistant)

Construct a builder with an EntropySourceProvider based on the passed in SecureRandom and the passed in value for prediction resistance.

Any SecureRandom created from a builder constructed like this will make use of input passed to SecureRandom.setSeed() if the passed in SecureRandom does for its generateSeed() call.

Parameters:

entropySource - the SecureRandom acting as a source of entropy for DRBGs made by this builder.

predictionResistant - true if the SecureRandom seeder can be regarded as predictionResistant.

SP800SecureRandomBuilder

public SP800SecureRandomBuilder(EntropySourceProvider entropySourceProvider)

Create a builder which makes creates the SecureRandom objects from a specified entropy source provider.

Note: If this constructor is used any calls to setSeed() in the resulting SecureRandom will be ignored.

Parameters:

entropySourceProvider - a provider of EntropySource objects.

Method Detail

setPersonalizationString

public SP800SecureRandomBuilder setPersonalizationString(byte[] personalizationString)

Set the personalization string for DRBG SecureRandoms created by this builder

Parameters:

personalizationString - the personalisation string for the underlying DRBG.

Returns:

the current builder.

setSecurityStrength

public SP800SecureRandomBuilder setSecurityStrength(int securityStrength)

Set the security strength required for DRBGs used in building SecureRandom objects.

Parameters:

securityStrength - the security strength (in bits)

Returns:

the current builder.

setEntropyBitsRequired

public SP800SecureRandomBuilder setEntropyBitsRequired(int entropyBitsRequired)

Set the amount of entropy bits required for seeding and reseeding DRBGs used in building SecureRandom objects.

Parameters:

entropyBitsRequired - the number of bits of entropy to be requested from the entropy source on each seed/reseed.

Returns:

the current builder.

buildHash

public SP800SecureRandom buildHash(Digest digest,
                                   byte[] nonce,
                                   boolean predictionResistant)

Build a SecureRandom based on a SP 800-90A Hash DRBG.

Parameters:

digest - digest algorithm to use in the DRBG underneath the SecureRandom.

nonce - nonce value to use in DRBG construction. SP 800-90A Rev. 1 sec. 8.6.7 requires either a value with at least (security strength / 2) bits of entropy, or a value expected to repeat no more often than a (security strength / 2)-bit random string would. The nonce may be null if the entropy source supplies the nonce's entropy along with the entropy input, that is, if setEntropyBitsRequired(int) is at least (3 * security strength / 2) and the source delivers that much entropy (SP 800-90A Rev. 1 sec. 8.6.7 and 9.1). A null nonce with less entropy than that is still accepted, but the resulting DRBG is then not compliant; this is not checked.

predictionResistant - specify whether the underlying DRBG in the resulting SecureRandom should reseed on each request for bytes.

Returns:

a SecureRandom supported by a Hash DRBG.

buildCTR

public SP800SecureRandom buildCTR(BlockCipher cipher,
                                  int keySizeInBits,
                                  byte[] nonce,
                                  boolean predictionResistant)

Build a SecureRandom based on a SP 800-90A CTR DRBG.

Parameters:

cipher - the block cipher to base the DRBG on.

keySizeInBits - key size in bits to be used with the block cipher.

nonce - nonce value to use in DRBG construction. SP 800-90A Rev. 1 sec. 8.6.7 requires either a value with at least (security strength / 2) bits of entropy, or a value expected to repeat no more often than a (security strength / 2)-bit random string would. The nonce may be null if the entropy source supplies the nonce's entropy along with the entropy input, that is, if setEntropyBitsRequired(int) is at least (3 * security strength / 2) and the source delivers that much entropy (SP 800-90A Rev. 1 sec. 8.6.7 and 9.1). A null nonce with less entropy than that is still accepted, but the resulting DRBG is then not compliant; this is not checked.

predictionResistant - specify whether the underlying DRBG in the resulting SecureRandom should reseed on each request for bytes.

Returns:

a SecureRandom supported by a CTR DRBG.

buildHMAC

public SP800SecureRandom buildHMAC(Mac hMac,
                                   byte[] nonce,
                                   boolean predictionResistant)

Build a SecureRandom based on a SP 800-90A HMAC DRBG.

Parameters:

hMac - HMAC algorithm to use in the DRBG underneath the SecureRandom.

nonce - nonce value to use in DRBG construction. SP 800-90A Rev. 1 sec. 8.6.7 requires either a value with at least (security strength / 2) bits of entropy, or a value expected to repeat no more often than a (security strength / 2)-bit random string would. The nonce may be null if the entropy source supplies the nonce's entropy along with the entropy input, that is, if setEntropyBitsRequired(int) is at least (3 * security strength / 2) and the source delivers that much entropy (SP 800-90A Rev. 1 sec. 8.6.7 and 9.1). A null nonce with less entropy than that is still accepted, but the resulting DRBG is then not compliant; this is not checked.

predictionResistant - specify whether the underlying DRBG in the resulting SecureRandom should reseed on each request for bytes.

Returns:

a SecureRandom supported by a HMAC DRBG.