com.rsa.jsafe
Class JSAFE_SecureRandom

java.lang.Object
  java.util.Random
      java.security.SecureRandom
          com.rsa.jsafe.JSAFE_SecureRandom

All Implemented Interfaces:

Cloneable, Serializable

public abstract class JSAFE_SecureRandom

extends SecureRandom

implements Cloneable, Serializable

This class defines secure pseudorandom number generation, as well as random number generation in hardware. For more information about pseudorandom number generation, refer to the Crypto-J Developer's Guide.

JSAFE_SecureRandom extends the java.security.SecureRandom class so that it can be used to replace the Sun JavaSoft classes. All Crypto-J classes that use this class actually request a java.security.SecureRandom Java class, so that you can use the standard Java classes instead of java.security.SecureRandom.

See Overview of Crypto-J for background and reference material on using and understanding Crypto-J.

Copyright © RSA Security Inc., 1997-2005. All rights reserved.

See Also:

Serialized Form

Method Summary
abstract  void	autoseed() This method generates seed bytes and uses them to seed an object.
void	clearSensitiveData() This method clears sensitive data from an object.
Object	clone() Overrides the default clone to produce a deep clone.
void	extraSeed(byte[] extraSeedBytes) Generates seed bytes and uses them to seed an object.
abstract  void	generateRandomBytes(byte[] randomOutput, int offset, int numberOfBytes) Generates pseudorandom bytes, placing them into the given buffer.
byte[]	generateRandomBytes(int numberOfBytes) Generates pseudorandom bytes, returning them in a new byte array of length numberOfBytes.
abstract  String	getAlgorithm() Returns the standard algorithm name.
int[]	getAlgorithmParameters() Returns a new int array containing the algorithm's parameters.
String	getDevice() Returns the name of the device of record.
String[]	getDeviceList() Returns a String array that describes all the devices used to execute the transformation.
static SecureRandom	getInstance(String transformation, String device) Builds an object that performs the transformation on the given device.
void	nextBytes(byte[] bytes) Fills the input buffer with pseudorandom bytes.
double	nextDouble() Generates a pseudorandom double (8-byte floating-point number) value.
float	nextFloat() Generates a pseudorandom float (4-byte floating-point number) value.
int	nextInt() Generates a pseudorandom int (4-byte integer) value.
long	nextLong() Generates a pseudorandom long (8-byte integer) value.
short	nextShort() Generates a pseudorandom short (2-byte integer) value.
abstract  void	seed(byte[] seedBytes) Seeds the pseudorandom number generator.
void	setSeed(byte[] seedBytes) Seeds the pseudorandom number generator.
void	setSeed(long seedLong) Seeds the pseudorandom number generator with the seedLong (8-byte integer) value.

 

Methods inherited from class java.security.SecureRandom

generateSeed, getInstance, getInstance, getProvider, getSeed

 

Methods inherited from class java.util.Random

nextBoolean, nextGaussian, nextInt

 

Methods inherited from class java.lang.Object

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

 

Method Detail

getInstance

public static SecureRandom getInstance(String transformation,
                                       String device)
                                throws NoSuchAlgorithmException

Builds an object that performs the transformation on the given device. Note that this instance of JSAFE_SecureRandom has not been seeded. A call to the setSeed() method, or other seeding methods, will seed the JSAFE_SecureRandom object. If a call is not made to setSeed(), the first call to the nextBytes() method will force the SecureRandom object to seed itself.

 Note:  Due to a change in java.security.SecureRandom (the base class for
        JSAFE_SecureRandom) in JDK 1.2, the getInstance method must
        be changed. In earlier versions of Crypto-J, the JSAFE_SecureRandom
        class had a typical getInstance method that took two Strings as arguments;
        this was not a problem because, at that time, the base class, SecureRandom,
        did not have a getInstance method. In Crypto-J versions 2.1 and later, the
        JSAFE_SecureRandom.getInstance method returns an instance of
        JSAFE_SecureRandom cast as a SecureRandom class, and throws
        java.security.NoSuchAlgorithmException.

        If you are updating code from Crypto-J version 2.0 or earlier, see the section
        "Updating JSAFE_SecureRandom.getInstance()" under "Random Number Generation" of the
        Crypto-J Developer's Guide for more information.
 

The value of transformation must be one of the following:

• "MD5Random"
• "SHA1Random"
• "FIPS186Random"
• "X931Random-s"
• "HWRandom/digest"

The value of s when used with "X931Random" is the number of streams, a value from 1 to 6.

 Note: "FIPS186Random" is a general purpose FIPS 140-2 compliant pseudo random number
       generator based on the on the FIPS 186 standard.
 

 Note:  Using "X931Random" will produce pseudo-random results in compliance with
        the X9.31 standard. If a hardware random number generator is not available,
        this software pseudo-random number generator is required to generate
        strong RSA key pairs. This pseudo-random number generator also requires a
        minimum number of seed bytes per stream.
 

The value of digest when used with "HWRandom" must be one of the following:

• "MD2"
• "MD5"
• "SHA1"
• "NoDigest"

 Note:  The digest value is for whitening the hardware results. To produce
        unwhitened bytes, use "NoDigest". Whitening the output of a random number
        generator means applying a post-processing algorithm to reduce patterns in
        the hardware bits and make them less predictable. The advantage of
        performing whitening in software as well as hardware is that an attacker
        must modify the hardware and the software to make the HRNG leak secret
        information. If you plan to use the random numbers directly, you should use
        "MD2", "MD5", or "SHA1" as the "HWRandom" digest value to apply additional
        whitening. If you are seeding a pseudo-random number generator,
        you can use "NoDigest" for optimal performance.
 

The device value is as follows: choice1[/choice2[...[/choicen]]] where the choices for device value are as follows:

• "Java"
• "Native"
• "Intel"

For "HWRandom", the only hardware device that is currently available is "Intel". The "Intel" device can only perform "HWRandom". For information on generating random numbers using the "Intel" device, see the Intel Security Hardware User's Guide.

Crypto-J tries to instantiate a class using the first choice; if it cannot, it tries the other choices.

 Note:  Do not attempt to use hardware versions of Crypto-J classes unless you are
        very familiar with the hardware. See the "Random Number Generation" section
        of the Crypto-J Developer's Guide, which describes hardware usage,
        its benefits, and its problems, as well as the Intel Security Hardware User's
        Guide.

 Note:  In JDK 1.1, java.security.SecureRandom autoseeds on instantiation
        if a seed is not provided. JSAFE_SecureRandom does not autoseed on
        instantiation, but does offer an autoseed() method for pseudo-random number generators.
        Autoseeding is not needed for hardware random number generators such as Intel's.
 

Examples

The first example demonstrates how to build a pseudo-random object in software:

  JSAFE_SecureRandom md5Random = (JSAFE_SecureRandom)
        JSAFE_SecureRandom.getInstance ("MD5Random", "Native/Java");
 

The second example demonstrates how to build a random object using the HWRandom algorithm. This object can later be used to seed a Crypto-J pseudo-random number generator (PRNG). To get a JSAFE_SecureRandom object, you should cast the result with JSAFE_SecureRandom.

   JSAFE_SecureRandom intelRandom = (JSAFE_SecureRandom)
        JSAFE_SecureRandom.getInstance("HWRandom/SHA1" , "Intel");
 

If the Intel hardware is not available, Crypto-J throws a NoSuchAlgorithmException. If the Intel hardware is available, Crypto-J creates an instance of JSAFE_SecureRandom that can perform Intel random number generation. If something goes wrong after this instance has been created, Crypto-J throws an IntelException. See the Intel Security Hardware User's Guide for further information.

Parameters:

transformation - The representation of the desired operation (for example, "MD5Random").

device - A list of devices used to build the object (for example, "Java", "Native/Java").

Returns:

A new JSAFE_SecureRandom object that performs the transformation on the given device.

Throws:

NoSuchAlgorithmException - If the device or devices cannot perform the designated algorithm, or if the transformation contains parameters that do not work.

See Also:

setSeed(long), seed(byte[]), extraSeed(byte[]), nextBytes(byte[]), generateRandomBytes(int)

getDevice

public String getDevice()

Returns the name of the device of record. Possible device values are:

• Java
• Native
• name of the specified device

Returns:

The device name.

getDeviceList

public String[] getDeviceList()

Returns a String array that describes all the devices used to execute the transformation. Because a transformation often consists of component algorithms, the implementation can consist of several component objects. Returns the names of the devices used by each component.

Returns:

A String array that describes the device used for a specific component.

getAlgorithmParameters

public int[] getAlgorithmParameters()

Returns a new int array containing the algorithm's parameters. This may be an array of length 0.

Returns:

A new int array that contains the parameters.

getAlgorithm

public abstract String getAlgorithm()

Returns the standard algorithm name.

Returns:

A String that describes the algorithm.

seed

public abstract void seed(byte[] seedBytes)

Seeds the pseudorandom number generator. This method uses the entire input buffer, and seeds an object. It uses all the bytes of the seedBytes array and can be called at any time. The seed method "adds" the new seed bytes, but does not replace any old seeding. Each call to seed(), autoseed(), or generateRandomBytes() updates the internal state of an object.

Parameters:

seedBytes - A byte array that alters the internal state of the PRNG.

extraSeed

public void extraSeed(byte[] extraSeedBytes)
               throws JSAFE_InputException

Generates seed bytes and uses them to seed an object. Provides "extra" seed bytes for PRNGs that use two kinds of seed, such as an X9.31 random seed.

To generate a random seed that complies with the X9.31 specification, there must be two independent streams of seeding. A standard seed is supplied by calling seed(), autoseed(), or generateRandomBytes(), and a user-supplied seed, by calling extraSeed(). Both seeds are required to maintain compliance with the X9.31 specification. If the underlying algorithm does not use two kinds of seed, this method will simply use these seed bytes as regular seed. This method uses the entire input buffer.

The size, in bytes, of the extraSeedBytes passed in to the extraSeed() method must be between 20 and 64 times the number of streams.

Parameters:

extraSeedBytes - The input, used as extra seed bytes if the algorithm uses two distinct types of seed.

Throws:

JSAFE_InputException - If the extra seed does not match the algorithm's expectations.

See Also:

seed(byte[]), setSeed(long)

autoseed

public abstract void autoseed()

This method generates seed bytes and uses them to seed an object. The technique used is based on the autoseeding from java.security.SecureRandom.

This method may take four or five seconds.

 Note:  JavaSoft provides the following cautionary statement regarding their
        autoseeding algorithm: We attempt to provide sufficient seed bytes to
        completely randomize the internal state of the generator (20 bytes). Note,
        however, that our seed generation algorithm has not been thoroughly studied
        or widely deployed. It relies on counting the number of times that the calling
        thread can yield while waiting for another thread to sleep for a specified
        interval.
 

setSeed

public void setSeed(long seedLong)

Seeds the pseudorandom number generator with the seedLong (8-byte integer) value.

Reseeds this random object, using the eight bytes contained in the seedLong parameter. The given seed supplements, rather than replaces, the existing seed. Thus, repeated calls are guaranteed never to reduce randomness.

Parameters:

seedLong - A long that alters the internal state of the PRNG.

See Also:

seed(byte[])

setSeed

public void setSeed(byte[] seedBytes)

Seeds the pseudorandom number generator. This method uses the entire input buffer.

Parameters:

seedBytes - A byte array that alters the internal state of the PRNG.

See Also:

seed(byte[])

nextBytes

public void nextBytes(byte[] bytes)

Fills the input buffer with pseudorandom bytes.

Parameters:

bytes - A buffer that is filled entirely with pseudorandom bytes.

See Also:

setSeed(long)

nextShort

public short nextShort()

Generates a pseudorandom short (2-byte integer) value.

Returns:

A pseudorandom short value.

nextInt

public int nextInt()

Generates a pseudorandom int (4-byte integer) value.

Returns:

A pseudorandom int value.

nextLong

public long nextLong()

Generates a pseudorandom long (8-byte integer) value.

Returns:

A pseudorandom long value.

nextDouble

public double nextDouble()

Generates a pseudorandom double (8-byte floating-point number) value. This method builds only positive values.

Returns:

A pseudorandom double value.

nextFloat

public float nextFloat()

Generates a pseudorandom float (4-byte floating-point number) value. This method builds only positive values.

Returns:

A pseudorandom float value.

generateRandomBytes

public byte[] generateRandomBytes(int numberOfBytes)

Generates pseudorandom bytes, returning them in a new byte array of length numberOfBytes.

Parameters:

numberOfBytes - The number of pseudorandom bytes to generate.

Returns:

A new byte array containing the pseudorandom output.

generateRandomBytes

public abstract void generateRandomBytes(byte[] randomOutput,
                                         int offset,
                                         int numberOfBytes)

Generates pseudorandom bytes, placing them into the given buffer. This method generates numberOfBytes random bytes and places them into the byte array randomOutput, beginning at offset.

This method is used as the basis of all random entities returned by this class (except seed bytes).

Parameters:

randomOutput - The buffer where the pseudorandom output is placed.

offset - The offset into randomOutput where the writing begins.

numberOfBytes - The number of pseudorandom bytes to generate.

clone

public Object clone()
             throws CloneNotSupportedException

Overrides the default clone to produce a deep clone. Overrides clone in class JSAFE_Object

Returns:

A copy of this object.

Throws:

CloneNotSupportedException - If the object cannot be cloned.

clearSensitiveData

public void clearSensitiveData()

This method clears sensitive data from an object. Although the finalizer clears the data, there is no guarantee the garbage collector will quickly call the finalizer. Allows a user to clear data as soon as possible. After calling clearSensitiveData(), an Init (not a ReInit) method is called to perform other operations with the object.