Main Page   Packages   Modules   Alphabetical List   Compound List   File List   Compound Members  

JSAFE_SecureRandom Class Reference

List of all members.

Public Methods

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 Methods

SecureRandom getInstance (String transformation, String device) throws NoSuchAlgorithmException

Protected Methods

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

Static Protected Methods

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

Private Methods

 JSAFE_SecureRandom ()
void setLongSeed (long seedLong)
byte[] serializeRandom ()

Static Private Methods

final void checkIntegrity ()
final boolean isInFIPSMode ()
synchronized SecureRandom getSeederSync ()
JSAFE_SecureRandom getInstance (String[] transformationNames, String[] deviceNames, JSAFE_DeviceBuilder deviceBuilder, JSAFE_DeviceBuilder[] deviceObjects) throws JSAFE_InvalidParameterException
JSAFE_SecureRandom deserializeRandom (String randomAlgorithm, byte[] oldRandom)

Private Attributes

String theDevice
String[] theDeviceList

Static Private Attributes

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

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.


Member Function Documentation

abstract void 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 JSAFE_SecureRandom::clearSensitiveData   [inline]
 

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 JSAFE_SecureRandom::clone   [inline]
 

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.

JSAFE_SecureRandom JSAFE_SecureRandom::deserializeRandom String    randomAlgorithm,
byte    oldRandom[]
[inline, static, private]
 

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 JSAFE_SecureRandom::extraSeed byte    extraSeedBytes[] [inline]
 

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 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 [] JSAFE_SecureRandom::generateRandomBytes int    numberOfBytes [inline]
 

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 JSAFE_SecureRandom::getAlgorithm   [pure virtual]
 

Returns the standard algorithm name.

Returns:
A String that describes the algorithm.

int [] JSAFE_SecureRandom::getAlgorithmParameters   [inline]
 

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 JSAFE_SecureRandom::getDevice   [inline]
 

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

  • Java
  • Native
  • name of the specified device

Returns:
The device name.

String [] JSAFE_SecureRandom::getDeviceList   [inline]
 

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.

JSAFE_SecureRandom JSAFE_SecureRandom::getInstance String    transformationNames[],
String    deviceNames[],
JSAFE_DeviceBuilder    deviceBuilder,
JSAFE_DeviceBuilder    deviceObjects[]
[inline, 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.

SecureRandom JSAFE_SecureRandom::getInstance String    transformation,
String    device
[inline, 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-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.
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.

synchronized SecureRandom JSAFE_SecureRandom::getSeederSync   [inline, 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 JSAFE_SecureRandom::nextBytes byte    bytes[] [inline]
 

Fills the input buffer with pseudorandom bytes.

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

double JSAFE_SecureRandom::nextDouble   [inline]
 

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

Returns:
A pseudorandom double value.

float JSAFE_SecureRandom::nextFloat   [inline]
 

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

Returns:
A pseudorandom float value.

int JSAFE_SecureRandom::nextInt   [inline]
 

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

Returns:
A pseudorandom int value.

long JSAFE_SecureRandom::nextLong   [inline]
 

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

Returns:
A pseudorandom long value.

short JSAFE_SecureRandom::nextShort   [inline]
 

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

Returns:
A pseudorandom short value.

abstract void 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 [] JSAFE_SecureRandom::serializeRandom   [inline, private]
 

Convert this object into a byte array for serialization.

Returns:
This object represented as a byte array.

void JSAFE_SecureRandom::setLongSeed long    seedLong [inline, 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 JSAFE_SecureRandom::setSeed byte    seedBytes[] [inline]
 

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 JSAFE_SecureRandom::setSeed long    seedLong [inline]
 

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 JSAFE_SecureRandom::fullyQualClassName [static, private]
 

Initial value:

    "com.rsa.jsafe.JSAFE_SecureRandom"

final String [] JSAFE_SecureRandom::interfaceListChain [static, private]
 

Initial value:

 {
    "com.rsa.jsafe.JA_AlgaeChainDigestRandom"
  }

final String [] 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 13:49:17 2005 for Dimitri by doxygen1.2.13 written by Dimitri van Heesch, © 1997-2001