org.randomness
Enum CSPRNG

java.lang.Object
  extended by java.lang.Enum<CSPRNG>
      extended by org.randomness.CSPRNG
All Implemented Interfaces:
Serializable, Comparable<CSPRNG>

public enum CSPRNG
extends Enum<CSPRNG>

List of implemented Cryptographically Secure Pseudorandom Number Generators that produces random numbers with properties that make it suitable for use in cryptography. A process (or data produced by a process) is said to be pseudorandom when the outcome is deterministic, yet also effectively random as long as the internal action of the process is hidden from observation. For cryptographic purposes, “effectively” means “within the limits of the intended cryptographic strength.”

PROVISIONAL API, WORK IN PROGRESS

A cryptographically strong random number minimally complies with the statistical random number generator tests specified in FIPS 140-2, Security Requirements for Cryptographic Modules, section 4.9.1. Additionally, CSPRNG must produce non-deterministic output. Therefore any seed material passed to a CSPRNG object must be unpredictable, and all CSPRNG output sequences must be cryptographically strong, as described in RFC 1750: Randomness Recommendations for Security.

Author:
Anton Kabysh (randomness adaptation),
Daniel Dyer (uncommons-math AES Counter),
Marcus Lippert, Martin During (Blum-Blum-Shub generator),
Benjamin Renaud, Josh Bloch, Gadi Guy (Java Native Generator),
Chuck McManis, Benjamin Renaud, Andreas Sterbenz (Java MD5 implementation),
Roger Riggs, Benjamin Renaud, Andreas Sterbenz, Valerie Peng (Java SHA1, SHA-256 and SHA-512 implementation),
Doug Lea (idea and implementation of java.util.concurrent.ThreadLocalRandom)
See Also:
Java ™ Cryptography Architecture - (JCA) Reference Guide, Comparison of cryptographic hash functions

, The FlexiProvider is a powerful toolkit for the Java Cryptography Architecture (JCA/JCE).


Enum Constant Summary
AES
          Non-linear random number generator based on the AES block cipher in counter mode.
BBS
          The BBS (or X2-mod-N) generator based on a paper written by L Blum, M Blum and M Shub in 1982 and is proved to be as secure as the factorization of the Modulus (which is a 1024 bit number).
BLOWFISH
          Non-linear random number generator based on the Blowfish block cipher in counter mode.
FORTUNA
          PROVISIONAL API, WORK IN PROGRESS Not implemented.
MD5
          Non-linear random number generator based on the MD5 cryptographic hash function in counter mode.
NATIVE
          Provides a native cryptographically strong random number generator supported by Java Platform (default instance of java.security.SecureRandom ).
SHA1
          Non-linear random number generator based on the SHA1 cryptographic hash function in counter mode.
SHA2
          Non-linear random number generator based on the SHA-256 cryptographic hash function in counter mode.
SHA512
          Non-linear random number generator based on the SHA-512 cryptographic hash function in counter mode.
VMPC
          VMPC ("Variably Modified Permutation Composition") is encryption technology designed by Bartosz Zoltak, publicly presented in 2004; The core of the technology is the VMPC one-way function, applied in an encryption algorithm - the VMPC stream cipher.
 
Field Summary
static AtomicInteger MAX_ENTROPY_INPUT_LENGTH
          Determine maximum length of entropy input string produced by entropy function in bytes; default value - 1024 bytes.
static AtomicInteger MAX_PERSONALIZATION_STRING_LENGTH
          Determine maximum personalization string length in bytes; default value - 1024 bytes.
static CSPRNG RIJNDAEL
          Synonym of AES algorithm.
static CSPRNG SECURE_RANDOM
          Synonym of NATIVE algorithm which SecureRandom is used.
 
Method Summary
 Cryptorandomness current()
          Returns a unique CSPRNG generator isolated to the current thread (thread local random).
 Cryptorandomness defaultInstance()
          Create's new instance of specified Cryptographically Random Number Generator wiht default configurable parameters.
 boolean isSupported()
          Checks whatever or not this CSPRNG is acessible on current platform.
 int seedlen()
          Returns the seed length used by underlying CSPRNG algorithm in bytes.
static CSPRNG valueOf(String name)
          Returns the enum constant of this type with the specified name.
static CSPRNG[] values()
          Returns an array containing the constants of this enum type, in the order they are declared.
 
Methods inherited from class java.lang.Enum
clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 

Enum Constant Detail

AES

public static final CSPRNG AES
Non-linear random number generator based on the AES block cipher in counter mode. Cipher increments counter before producing next random block.

AES is Advanced Encryption Standard as specified by NIST in a draft FIPS. Based on the Rijndael algorithm by Joan Daemen and Vincent Rijmen, AES is a 128-bit block cipher supporting keys of 128, 192, and 256 bits.

The AES Cryptorandomness based on JCE algorithm: AES/ECB/NoPadding.
The DRBG Mechanisms Based on Block Ciphers CTR_DRBG specified in Section 10.2 of NIST 800-90 Special Publication (p. 45). This recommendations was used to construct underlying implementation of block Cipher Cryptorandomness in counter mode.

The default key size is 16 bytes (128 bit). Other allowed key length is 24 and 32 bytes. Key length can be configured to one of this values if it's specified key length is supported by underlying security provider. You can define maximum allowed key length on your platform (in bits) by calling:

int keySizeBits = Cipher.getMaxAllowedKeyLength("AES/ECB/NoPadding");

The output block length is equal to key length.

Instances of this CSPRNG is internally buffered with buffer size equal to output block length.

See Also:
Advanced Encryption Standard

BBS

public static final CSPRNG BBS
The BBS (or X2-mod-N) generator based on a paper written by L Blum, M Blum and M Shub in 1982 and is proved to be as secure as the factorization of the Modulus (which is a 1024 bit number).

The generator works in three steps:

  1. The generator uses an internal 25 bytes (200 bit) seed (not configurable), so it is inefficient to do something like a "brute force" attack (i.e. enumerate all possible seeds).
  2. In order to generate the parameters used during the generation, the internal seed is expanded using a Linear Congruential Generator (LCG). This generator is not secure in a cryptographical manner, but as no output of the (LCG) is visible to the outside world, this is no problem. The parameters are the seed X and the modulus N which is the product of two different prime numbers P,Q of equal bit length. N is at least a 1024 bit number. The parameters are generated after the instantiation and after each call to reseed.
  3. Using these parameters, the generator iteratively determines a new X by raising X to the power of 2 modulo N. During each iteration the log2(|N|)-least-significant bits of the binary representation of X are collected and form the output of the generator.

Since:
1986
See Also:
Wikipedia - Blum Blum Shub generator, Integer factorization

BLOWFISH

public static final CSPRNG BLOWFISH
Non-linear random number generator based on the Blowfish block cipher in counter mode. Cipher increments counter before producing next random block.

Blowfish: is a keyed, symmetric block cipher, designed in 1993 by Bruce Schneier and included in a large number of cipher suites and encryption products. Blowfish provides a good encryption rate in software and no effective cryptanalysis of it has been found to date. However, the Advanced Encryption Standard now receives more attention.
The DRBG Mechanisms Based on Block Ciphers CTR_DRBG specified in Section 10.2 of NIST 800-90 Special Publication. This recommendations was used to construct underlying implementation of block Cipher Cryptorandomness in counter mode.

The Blowfish Cryptorandomness based on JCE algorithm: Blowfish.

The default key size is 16 bytes (128 bit). Other allowed key length is 24 and 32 bytes. Key length can be configured to one of this values. If it's specified key length is supported by underlying security provider. You can define maximum allowed key length on your platform (in bits) by calling:

int keySizeBits = Cipher.getMaxAllowedKeyLength("Blowfish");

The output block length is equal to key length.

Instances of this CSPRNG is internally buffered with buffer size equal to output block length.

See Also:
Wikipedia - Blowfish (cipher), Wikipedia - Bruce Schneier

MD5

public static final CSPRNG MD5
Non-linear random number generator based on the MD5 cryptographic hash function in counter mode. The MD5 hash function is used to compute an message digest from a internal state, seed and counter. Result output digest is used to update the internal state and as a random output. After cycle of operations, the seed is also updated.

It is an implementation of the RSA Data Security Inc. MD5 algorithm as described in RFC 1321.
The DRBG Mechanisms Based on Hash Functions Hash_DRBG specified in Section 10.1 of NIST 800-90 Special Publication (p. 34). This recommendations is used to construct underlying implementation of MessageDigest Cryptorandomness in counter mode.

This generator in default use the MD5 implementation from Sun, as follows: MessageDigest digest = MessageDigest.getInstance("MD5"); If this implementation of MD5 message digest is not present in the system (throws NoSuchAlgorithmException), than used internal implementation.

This generator uses at minimum 16 byte seed. Seed size can be configured to arbitrary value not lower than default.

The output block is 16 bytes.

Instances of this CSPRNG is internally buffered with buffer size equal to output block length.

See Also:
Wikipedia - MD5, RFC 1321 - The MD5 Message-Digest Algorithm

NATIVE

public static final CSPRNG NATIVE
Provides a native cryptographically strong random number generator supported by Java Platform (default instance of java.security.SecureRandom ). The default instance of SecureRandom creates secure random number generator (RNG) implementing the default random number algorithm.

Traverses the list of registered security Providers, starting with the most preferred Provider. A new object encapsulating the SecureRandomSpi implementation from the first Provider that supports a SecureRandom (RNG) algorithm is returned. If none of the Providers support a RNG algorithm, then an implementation-specific default is returned.

This is a most commonly used generator, that should be work on the all platforms. This generator adapts himself to platform-specific properties. E.g. on Linux uses /dev/random or /dev/urandom. Usually it uses a SHA1PRNG instance based on SHA1 hash function. This generator uses at minimum a 20 byte (160 bit) seed for this generator. Seed size can be configured to arbitrary value such, that is no lower than default. This generator is used to seed itself, as in original SecureRandom, but seed bytes is processed by derivation function.

See Also:
Open JDK sun.security.provider.SecureRandom implementation

SHA1

public static final CSPRNG SHA1
Non-linear random number generator based on the SHA1 cryptographic hash function in counter mode. The SHA1 hash function is used to compute an message digest from a internal state, seed and counter. Result output digest is used to update the internal state and as a random output. After cycle of operations, the seed is also updated.

Secure Hash Algorithm SHA1 developed by the National Institute of Standards and Technology along with the National Security Agency as described in FIPS 180-3.
The DRBG Mechanisms Based on Hash Functions Hash_DRBG specified in Section 10.1 of NIST 800-90 Special Publication (p. 34). This recommendations is used to construct underlying implementation of MessageDigest Cryptorandomness in counter mode.

This generator in default use the SHA1 implementation from Sun, as follows: MessageDigest digest = MessageDigest.getInstance("SHA1"); If this implementation is not present in the system (throws NoSuchAlgorithmException), than execution is stopped, throwing unchecked error (InternalError). Internal implementation of SHA1 message digest is not supported yet.

SHA1 digest generator uses 55 byte (440 bits) seed, as specified at NIST SP 800-80, Table 2: Definitions for Hash-Based DRBG Mechanisms. Seed size can be configured to arbitrary value not lower than default.

The output block is 20 bytes.

Instances of this CSPRNG is internally buffered with buffer size equal to output block length.

See Also:
Wikipedia - SHA1, FIPS 180-3 - Secure Hash Standard (PDF)

SHA2

public static final CSPRNG SHA2
Non-linear random number generator based on the SHA-256 cryptographic hash function in counter mode. The SHA-256 hash function is used to compute an message digest from a internal state, seed and counter. Result output digest is used to update the internal state and as a random output. After cycle of operations, the seed is also updated.

Secure Hash Algorithm SHA-256 developed by the National Institute of Standards and Technology along with the National Security Agency as described in FIPS 180-3.
The DRBG Mechanisms Based on Hash Functions Hash_DRBG specified in Section 10.1 of NIST 800-90 Special Publication (p. 34). This recommendations is used to construct underlying implementation of MessageDigest Cryptorandomness in counter mode.

This generator in default use the SHA2 implementation from Sun, as follows: MessageDigest digest = MessageDigest.getInstance("SHA-256"); If this implementation is not present in the system (throws NoSuchAlgorithmException), than execution is stopped, throwing unchecked error (InternalError). Internal implementation of SHA2 hash function is not supported yet.

SHA2 digest generator uses 55 byte (440 bits) seed, as specified at NIST SP 800-80, Table 2: Definitions for Hash-Based DRBG Mechanisms. Seed size can be configured to arbitrary value not lower than default.

The output block is 32 bytes.

Instances of this CSPRNG is internally buffered (witout external Instances of this CSPRNG is internally buffered with buffer size equal to output block length.

See Also:
Wikipedia - SHA2, FIPS 180-3 - Secure Hash Standard (PDF)

SHA512

public static final CSPRNG SHA512
Non-linear random number generator based on the SHA-512 cryptographic hash function in counter mode. The SHA-512 hash function is used to compute an message digest from a internal state, seed and counter. Result output digest is used to update the internal state and as a random output. After cycle of operations, the seed is also updated.

Secure Hash Algorithm SHA-512 developed by the National Institute of Standards and Technology along with the National Security Agency
The DRBG Mechanisms Based on Hash Functions Hash_DRBG specified in Section 10.1 of NIST 800-90 Special Publication (p. 34). This recommendations is used to construct underlying implementation of MessageDigest Cryptorandomness in counter mode.

This generator in default use the SHA-512 implementation from Sun, as follows: MessageDigest digest = MessageDigest.getInstance("SHA-512"); If this implementation is not present in the system (throws NoSuchAlgorithmException), than execution is stopped, throwing unchecked error (InternalError). Internal implementation of SHA-512 hash function is not supported yet.

SHA-512 digest generator uses 111 byte (888 bits) seed, as specified at NIST SP 800-80, Table 2: Definitions for Hash-Based DRBG Mechanisms. Seed size can be configured to arbitrary value not lower than default.

The output block is 64 bytes.

Instances of this CSPRNG is internally buffered with buffer size equal to output block length.

See Also:
Wikipedia - SHA2, FIPS 180-3 - Secure Hash Standard (PDF)

VMPC

public static final CSPRNG VMPC
VMPC ("Variably Modified Permutation Composition") is encryption technology designed by Bartosz Zoltak, publicly presented in 2004; The core of the technology is the VMPC one-way function, applied in an encryption algorithm - the VMPC stream cipher.

VMPC one way function uses 64 byte (512 bits) seed.

Since:
2004
See Also:
Wikipedia - VMPC, VMPC Home Page

FORTUNA

public static final CSPRNG FORTUNA

PROVISIONAL API, WORK IN PROGRESS

Not implemented.

Field Detail

SECURE_RANDOM

public static final CSPRNG SECURE_RANDOM
Synonym of NATIVE algorithm which SecureRandom is used.


RIJNDAEL

public static final CSPRNG RIJNDAEL
Synonym of AES algorithm.


MAX_ENTROPY_INPUT_LENGTH

public static final AtomicInteger MAX_ENTROPY_INPUT_LENGTH
Determine maximum length of entropy input string produced by entropy function in bytes; default value - 1024 bytes. The default Cryptorandomness implementation uses a hash based derivation function.

The max_length recomendations:


MAX_PERSONALIZATION_STRING_LENGTH

public static final AtomicInteger MAX_PERSONALIZATION_STRING_LENGTH
Determine maximum personalization string length in bytes; default value - 1024 bytes.
The default Cryptorandomness implementation uses a hash based derivation function.

The max_personalization_string_length recomendations:

Method Detail

values

public static CSPRNG[] values()
Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:
for (CSPRNG c : CSPRNG.values())
    System.out.println(c);

Returns:
an array containing the constants of this enum type, in the order they are declared

valueOf

public static CSPRNG valueOf(String name)
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:
name - the name of the enum constant to be returned.
Returns:
the enum constant with the specified name
Throws:
IllegalArgumentException - if this enum type has no constant with the specified name
NullPointerException - if the argument is null

defaultInstance

public final Cryptorandomness defaultInstance()
Create's new instance of specified Cryptographically Random Number Generator wiht default configurable parameters. This method return's null if specified generator is not supported at this moment (e.g. no enougth entropy, or algorithm is not present is the system).

Returns:
a new Cryptorandomness generator (created wiht default parameters), or null if this generator is not supported by platform at this time.
See Also:
Cryptorandomness.from(CSPRNG)

current

public Cryptorandomness current()
Returns a unique CSPRNG generator isolated to the current thread (thread local random). An attempt to use this instance from annoter thread will throw ConcurrentModificationException.

Usages of this class should typically be of the form: CSPRNG.XXX.current().nextX(...) (where XXX - one of implemented CSPRNG generators, and X is Int, Long , etc). When all usages are of this form, it is never possible to accidently share a thread local random across multiple threads.

The thread local random instance is unique for parent thread, so locality can be cheked as:

 public boolean isThreadLocal(Randomness rnd) {
        return CSPRNG.XXX.current() == rnd;
 }
 
where XXX - one of implemented CSPRNG generators

Returns:
the thread local instance of CSPRNG for current thread.
See Also:
ThreadLocal,
PRNG#current() Thread local for Pseudorandomness,,
TRNG#current() Thread-local for Truerandomness.

seedlen

public int seedlen()
Returns the seed length used by underlying CSPRNG algorithm in bytes. The minimum seed length depends on the CSPRNG mechanism and the security strength required by the consuming application.

Note: The default Cryptorandomness.getEntropyInput(int, int, int) implementation specify that min_length of required entropy shold not be greater than max_length constant. In other words, maximum seedlen value is limited by MAX_ENTROPY_INPUT_LENGTH value, when Cryptorandomness.getEntropyInput(int, int, int) function is called.

Predefined values:

Generator Seed size
AES 16 bytes Configurable: 16, 24, 32 bytes seed, if supported by platform
BBS 25 bytes Not configurable
BLOWFISH 16 bytes Configurable: 16, 24, 32 bytes seed, if supported by platform
MD5 16 bytes Configurable (any value greater than default)
NATIVE 20 bytes Configurable (any value greater than default)
SHA1 55 bytes Configurable (any value greater than default)
SHA2 55 bytes Configurable (any value greater than default)
SHA-512 111 bytes Configurable (any value greater than default)
VMPC 64 bytes Configurable (any value greater than default)

Returns:
return default initial seed length for particular CSPRNG in bytes.

isSupported

public boolean isSupported()
Checks whatever or not this CSPRNG is acessible on current platform.

Returns:
true if generators of this type can be instantiated on this platform, false otherwise.