Main Page | Modules | Packages | Alphabetical List | Class List | Directories | Class Members

com.rsa.jsafe.JSAFE_SecureRandom Class Reference

List of all members.

Detailed Description

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.


Public Member Functions

String getDevice ()
String[] getDeviceList ()
int[] getAlgorithmParameters ()
abstract String getAlgorithm ()
abstract void seed (byte[] seedBytes)
void extraSeed (byte[] extraSeedBytes) throws JSAFE_InputException
abstract void autoseed ()
void setSeed (long seedLong)
void setSeed (byte[] seedBytes)
void nextBytes (byte[] bytes)
short nextShort ()
int nextInt ()
long nextLong ()
double nextDouble ()
float nextFloat ()
byte[] generateRandomBytes (int numberOfBytes)
abstract void generateRandomBytes (byte[] randomOutput, int offset, int numberOfBytes)
Object clone () throws CloneNotSupportedException
void clearSensitiveData ()

Static Public Member Functions

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

Protected Member Functions

void prngCheck (byte[] previousBlock, int previousOffset, byte[] currentBlock, int currentOffset, int count)
void setJSAFELevelValues (JSAFE_SecureRandom original) throws CloneNotSupportedException

Static Protected Member Functions

static SecureRandom getSeeder ()
static byte[] getRandomSeed (int numBytes)

Package Functions

byte[] serializeRandom ()

Static Package Functions

static final void checkIntegrity ()
static final boolean isInFIPSMode ()
static JSAFE_SecureRandom deserializeRandom (String randomAlgorithm, byte[] oldRandom)

Private Member Functions

void setLongSeed (long seedLong)

Static Private Member Functions

static synchronized SecureRandom getSeederSync ()
static JSAFE_SecureRandom getInstance (String[] transformationNames, String[] deviceNames, JSAFE_DeviceBuilder deviceBuilder, JSAFE_DeviceBuilder[] deviceObjects) throws JSAFE_InvalidParameterException

Private Attributes

String theDevice
String[] theDeviceList

Static Private Attributes

static SecureRandom seeder = null
static final boolean[] strictHW = { true, false }
static final String[] interfaceListHW
static final boolean[] strictChain = { true }
static final String[] interfaceListChain
static final String fullyQualClassName


Member Function Documentation

abstract void com.rsa.jsafe.JSAFE_SecureRandom.autoseed  )  [pure virtual]
 

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.
 

void com.rsa.jsafe.JSAFE_SecureRandom.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.

Object com.rsa.jsafe.JSAFE_SecureRandom.clone  )  throws CloneNotSupportedException
 

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

Returns:
A copy of this object.
Exceptions:
CloneNotSupportedException If the object cannot be cloned.

static JSAFE_SecureRandom com.rsa.jsafe.JSAFE_SecureRandom.deserializeRandom String  randomAlgorithm,
byte[]  oldRandom
[static, package]
 

Convert the input byte array into a JSAFE_SecureRandom object.

Parameters:
randomAlgorithm The name of the random algorithm to use (e.g., "MD5Random").
oldRandom A byte array that is the representation of the old random object.
Returns:
A new JSAFE_SecureRandom object.

void com.rsa.jsafe.JSAFE_SecureRandom.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.

See also:
seed

setSeed

Parameters:
extraSeedBytes The input, used as extra seed bytes if the algorithm uses two distinct types of seed.
Exceptions:
JSAFE_InputException If the extra seed does not match the algorithm's expectations.

abstract void com.rsa.jsafe.JSAFE_SecureRandom.generateRandomBytes byte[]  randomOutput,
int  offset,
int  numberOfBytes
[pure virtual]
 

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.

byte [] com.rsa.jsafe.JSAFE_SecureRandom.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.

abstract String com.rsa.jsafe.JSAFE_SecureRandom.getAlgorithm  )  [pure virtual]
 

Returns the standard algorithm name.

Returns:
A String that describes the algorithm.

int [] com.rsa.jsafe.JSAFE_SecureRandom.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.

String com.rsa.jsafe.JSAFE_SecureRandom.getDevice  ) 
 

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

  • Java
  • Native
  • name of the specified device

Returns:
The device name.

String [] com.rsa.jsafe.JSAFE_SecureRandom.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.

static JSAFE_SecureRandom com.rsa.jsafe.JSAFE_SecureRandom.getInstance String[]  transformationNames,
String[]  deviceNames,
JSAFE_DeviceBuilder  deviceBuilder,
JSAFE_DeviceBuilder[]  deviceObjects
throws JSAFE_InvalidParameterException [static, private]
 

Build an object that performs the operation represented by the array transformationNames on the device or devices specified by deviceNames.

The deviceBuilder is the current device trying to build the object. If this device builder wants to look at other devices, it can through deviceNames and deviceObjects.

Parameters:
transformationNames An array of Strings specifying the components of the transformation.
deviceNames An array of Strings specifying the user-requested devices.
deviceBuilder The device builder to use.
deviceObjects An array of device builder objects (elements may be null because not yet instantiated).
Returns:
A new JSAFE_SecureRandom object that performs the transformation.
Exceptions:
JSAFE_InvalidParameterException If the transformation contains parameters that do not work.

static SecureRandom com.rsa.jsafe.JSAFE_SecureRandom.getInstance String  transformation,
String  device
throws NoSuchAlgorithmException [static]
 

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-<em>s</em>"
  • "HWRandom/<em>digest</em>"
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.
See also:
setSeed

seed

extraSeed

nextBytes

generateRandomBytes

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.
Exceptions:
NoSuchAlgorithmException If the device or devices cannot perform the designated algorithm, or if the transformation contains parameters that do not work.

static synchronized SecureRandom com.rsa.jsafe.JSAFE_SecureRandom.getSeederSync  )  [static, private]
 

Instantiates the global seed generator if it hasn't beeen done already. Synchronized methods are expensive so this will be called by an unsynchronized one only if the instance is null.

void com.rsa.jsafe.JSAFE_SecureRandom.nextBytes byte[]  bytes  ) 
 

Fills the input buffer with pseudorandom bytes.

See also:
setSeed
Parameters:
bytes A buffer that is filled entirely with pseudorandom bytes.

double com.rsa.jsafe.JSAFE_SecureRandom.nextDouble  ) 
 

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

Returns:
A pseudorandom double value.

float com.rsa.jsafe.JSAFE_SecureRandom.nextFloat  ) 
 

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

Returns:
A pseudorandom float value.

int com.rsa.jsafe.JSAFE_SecureRandom.nextInt  ) 
 

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

Returns:
A pseudorandom int value.

long com.rsa.jsafe.JSAFE_SecureRandom.nextLong  ) 
 

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

Returns:
A pseudorandom long value.

short com.rsa.jsafe.JSAFE_SecureRandom.nextShort  ) 
 

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

Returns:
A pseudorandom short value.

abstract void com.rsa.jsafe.JSAFE_SecureRandom.seed byte[]  seedBytes  )  [pure virtual]
 

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.

byte [] com.rsa.jsafe.JSAFE_SecureRandom.serializeRandom  )  [package]
 

Convert this object into a byte array for serialization.

Returns:
This object represented as a byte array.

void com.rsa.jsafe.JSAFE_SecureRandom.setLongSeed long  seedLong  )  [private]
 

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

Parameters:
seedLong A long, the bits of which are used to alter the internal state of the PRNG.

void com.rsa.jsafe.JSAFE_SecureRandom.setSeed byte[]  seedBytes  ) 
 

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

See also:
seed
Parameters:
seedBytes A byte array that alters the internal state of the PRNG.

void com.rsa.jsafe.JSAFE_SecureRandom.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.

See also:
seed
Parameters:
seedLong A long that alters the internal state of the PRNG.


Member Data Documentation

final String com.rsa.jsafe.JSAFE_SecureRandom.fullyQualClassName [static, private]
 

Initial value:

    "com.rsa.jsafe.JSAFE_SecureRandom"

final String [] com.rsa.jsafe.JSAFE_SecureRandom.interfaceListChain [static, private]
 

Initial value:

 {
    "com.rsa.jsafe.JA_AlgaeChainDigestRandom"
  }

final String [] com.rsa.jsafe.JSAFE_SecureRandom.interfaceListHW [static, private]
 

Initial value:

 {
    "com.rsa.jsafe.JA_AlgaeRandom",
    "com.rsa.jsafe.JA_AlgaeDigest"
  }


The documentation for this class was generated from the following file:
Generated on Mon Aug 1 14:00:09 2005 for Dimitri by  doxygen 1.4.4