SP800SecureRandomBuilder (Bouncy Castle Library 1.54 API Specification)
Date: 2015-12-29

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).

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `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

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `SP800SecureRandom` | `buildCTR(BlockCipher cipher, int keySizeInBits, byte[] nonce, boolean predictionResistant)` Build a SecureRandom based on a SP 800-90A CTR DRBG.
    `SP800SecureRandom` | `buildDualEC(Digest digest, byte[] nonce, boolean predictionResistant)` Build a SecureRandom based on a SP 800-90A Dual EC DRBG using the NIST point set.
    `SP800SecureRandom` | `buildDualEC(DualECPoints[] pointSet, Digest digest, byte[] nonce, boolean predictionResistant)` Deprecated. Don't use this for anything other than research purposes. It appears this construct is simply not safe.
    `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` -
        `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.
        `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.
        `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.
        `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.

    - #### buildDualEC

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

      Build a SecureRandom based on a SP 800-90A Dual EC DRBG using the NIST point set.
      Parameters:
        `digest` - digest algorithm to use in the DRBG underneath the SecureRandom.
        `nonce` - nonce value to use in DRBG construction.
        `predictionResistant` - specify whether the underlying DRBG in the resulting SecureRandom should reseed on each request for bytes.
      Returns:
        a SecureRandom supported by a Dual EC DRBG.

    - #### buildDualEC

          public SP800SecureRandom buildDualEC(DualECPoints[] pointSet,
                                      Digest digest,
                                      byte[] nonce,
                                      boolean predictionResistant)

      Deprecated. Don't use this for anything other than research purposes. It appears this construct is simply not safe.
      Build a SecureRandom based on a SP 800-90A Dual EC DRBG according to a defined point set.
      Parameters:
        `pointSet` - an array of DualECPoints to use for DRB generation.
        `digest` - digest algorithm to use in the DRBG underneath the SecureRandom.
        `nonce` - nonce value to use in DRBG construction.
        `predictionResistant` - specify whether the underlying DRBG in the resulting SecureRandom should reseed on each request for bytes.
      Returns:
        a SecureRandom supported by a Dual EC DRBG.