com.entrust.toolkit.security.crypto.random

Class X9_31using3DES

java.lang.Object

java.security.SecureRandomSpi

com.entrust.toolkit.security.crypto.random.FIPS140_2Compliant

com.entrust.toolkit.security.crypto.random.X9_31

com.entrust.toolkit.security.crypto.random.X9_31using3DES

All Implemented Interfaces:

java.io.Serializable

public class X9_31using3DES
extends X9_31

A software based implementation of the X9.31 pseudo-random number generator (PRNG) using a DESede cipher and a 192-bit key.

An instance of this algorithm can be obtained using the Java Cryptography Architecture (JCA), by requesting a 'X9_31usingDESede' PRNG from the Entrust cryptographic service provider. This can be done using the following call:

SecureRandom.getInstance("X9_31usingDESede", "Entrust");

FIPS 140-2:

This class is part of the Toolkit's FIPS 140-2 cryptographic module and contains APIs that are considered part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; refer to the API documentation for further details

Since:

7.0

See Also:

Serialized Form

Constructor Summary

Constructors

Modifier	Constructor and Description
	X9_31using3DES() The constructor; creates a new instance of the X9_31using3DES pseudo-random number generation algorithm.
protected	X9_31using3DES(byte[] seed, boolean gatherDT) A constructor; creates a new instance of the X9_31using3DES pseudo-random number generation algorithm initialized with the indicated initial seed.

Method Summary

Modifier and Type	Method and Description
protected void	engineSetSeed(byte[] seed) Reseeds this random object.
static void	runFipsKat() Runs a FIPS 140-2 known answer test on this PRNG.

Methods inherited from class com.entrust.toolkit.security.crypto.random.FIPS140_2Compliant

engineGenerateSeed, engineNextBytes

Methods inherited from class java.lang.Object

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

Constructor Detail

X9_31using3DES

public X9_31using3DES()
               throws java.lang.SecurityException

The constructor; creates a new instance of the X9_31using3DES pseudo-random number generation algorithm.

Applications should not use this constructor, instead the signature algorithm should be requested from the appropriate JCA/JCE cryptographic service provider as follows: SecureRandom.getInstance("X9_31using3DES", "Entrust").

FIPS 140-2:

FIPS Service: Modify Object

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call)
• status output interface (exceptions)

Throws:

java.lang.SecurityException

X9_31using3DES

protected X9_31using3DES(byte[] seed,
                         boolean gatherDT)
                  throws java.lang.IllegalArgumentException,
                         java.lang.SecurityException

A constructor; creates a new instance of the X9_31using3DES pseudo-random number generation algorithm initialized with the indicated initial seed.

This creates a Triple DES cipher operating in ECB mode with no padding. It initializes the cipher with a 192-bit Triple DES key that is created the initial seed. It also initializes the internal seed data V from the initial seed.

Only the first 256 bits of the seed provided are used, and the seed is automatically wiped from memory following usage.

The gatherDT parameter allows the caller to configure whether the Date/Time vector (DT) will be gathered from the system for every round or not. When set to false and the Toolkit is operating in non-FIPS mode, a DT of all zeros will be used (allows known answer testing).

The initial seed MUST always be a cryptographically strong seed. This requires that the entropy is evenly distributed over the seed bits (done through hashing).

FIPS 140-2:

Although this API is externally accessible (protected), it is intended for internal use only and MUST NOT be called externally by the operator when operating in FIPS mode. Since its use is prohibited, this API is not part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module.

Parameters:

seed - the initial seed

gatherDT - indicates whether additional entropy should be gathered and used as DT on every iteration of the algorithm (combats entropy leakage)

Throws:

java.lang.IllegalArgumentException - if seed does not contain 256 bits of data

java.lang.SecurityException - if the Entrust provider is not installed or the Toolkit is not permitted to do cryptographic operations (in the FIPS Error state)

Method Detail

runFipsKat

public static void runFipsKat()

Runs a FIPS 140-2 known answer test on this PRNG.

This API is intended for internal use only during initialization in FIPS_OPERATIONAL mode; it should NEVER be called externally.

FIPS 140-2:

FIPS Service: Cryptographic Operation

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call)
• status output interface (exceptions)

Throws:

Fips140ErrorStateException - [FIPS 140-2 status output] thrown if the Toolkit is not allowed to perform cryptographic operations or the self-test fails

engineSetSeed

protected final void engineSetSeed(byte[] seed)
                            throws java.lang.SecurityException

Description copied from class: FIPS140_2Compliant

Reseeds this random object.

The given seed supplements, rather than replaces, the existing seed. Thus, repeated calls are guaranteed never to reduce randomness.

This implementation DOES NOT allow the caller to set the initial seed, even when the caller follows the call to SecureRandom.getInstance() method with a call to the setSeed() method. This ensures that it is impossible to have an initial seed that is not cryptographically strong.

The seed that is passed in is not used directly; instead the seed is hashed before prior to use. The hashing is done because the entropy of the provided seed may not be spread evenly through all of the seed bits (no way to guarantee a cryptographically strong seed will be passed in the API). By passing the seed through a hash (message digest) algorithm, the entropy is spread (more or less) evenly through all of the bits.

Once the provided seed has been hashed, the result is used to supplement (not replace) the existing internal seed data. Following this call, the seed passed is NOT automatically wiped from memory; this SHOULD be done manually. All internal temporary data used is in this call is also automatically wiped following usage.

FIPS 140-2:

FIPS Service: Modify Object

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call)
• data input interface (parameters)
• status output interface (exceptions)

Specified by:

engineSetSeed in class FIPS140_2Compliant

Parameters:

seed - [FIPS 140-2 data input] [FIPS 140-2 CSP] the seed.

Throws:

java.lang.SecurityException