RSA BSAFE CRYPTO-J

Cryptographic Components for Java

JSAFE Javadoc JCE Javadoc Search

JSAFE_SecureRandom Class Reference

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.

List of all members.

Public Methods

String JSAFE_SecureRandom:: getDevice ()
 Returns the name of the device of record. More...

String [] JSAFE_SecureRandom:: getDeviceList ()
 Returns a String array that describes all the devices used to execute the transformation. More...

int [] JSAFE_SecureRandom:: getAlgorithmParameters ()
 Returns a new int array containing the algorithm's parameters. More...

abstract String JSAFE_SecureRandom:: getAlgorithm ()
 Returns the standard algorithm name. More...

abstract void JSAFE_SecureRandom:: seed (byte[] seedBytes)
 Seeds the pseudorandom number generator. More...

void JSAFE_SecureRandom:: extraSeed (byte[] extraSeedBytes) throws JSAFE_InputException
 Generates seed bytes and uses them to seed an object. More...

abstract void JSAFE_SecureRandom:: autoseed ()
 This method generates seed bytes and uses them to seed an object. More...

void JSAFE_SecureRandom:: setSeed (long seedLong)
 Seeds the pseudorandom number generator with the seedLong (8-byte integer) value. More...

void JSAFE_SecureRandom:: setSeed (byte[] seedBytes)
 Seeds the pseudorandom number generator. More...

void JSAFE_SecureRandom:: nextBytes (byte[] bytes)
 Fills the input buffer with pseudorandom bytes. More...

short JSAFE_SecureRandom:: nextShort ()
 Generates a pseudorandom short (2-byte integer) value. More...

int JSAFE_SecureRandom:: nextInt ()
 Generates a pseudorandom int (4-byte integer) value. More...

long JSAFE_SecureRandom:: nextLong ()
 Generates a pseudorandom long (8-byte integer) value. More...

double JSAFE_SecureRandom:: nextDouble ()
 Generates a pseudorandom double (8-byte floating-point number) value. More...

float JSAFE_SecureRandom:: nextFloat ()
 Generates a pseudorandom float (4-byte floating-point number) value. More...

byte [] JSAFE_SecureRandom:: generateRandomBytes (int numberOfBytes)
 Generates pseudorandom bytes, returning them in a new byte array of length numberOfBytes. More...

abstract void JSAFE_SecureRandom:: generateRandomBytes (byte[] randomOutput, int offset, int numberOfBytes)
 Generates pseudorandom bytes, placing them into the given buffer. More...

Object JSAFE_SecureRandom:: clone () throws CloneNotSupportedException
 Overrides the default clone to produce a deep clone. More...

void JSAFE_SecureRandom:: clearSensitiveData ()
 This method clears sensitive data from an object. More...


Static Public Methods

SecureRandom JSAFE_SecureRandom:: getInstance (String transformation, String device) throws NoSuchAlgorithmException
 Builds an object that performs the transformation on the given device. More...

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 (    )  throws CloneNotSupportedException [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.

void JSAFE_SecureRandom::extraSeed (  byte    extraSeedBytes[] )  throws JSAFE_InputException [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.

SecureRandom JSAFE_SecureRandom::getInstance (  String    transformation,
String    device
)  throws NoSuchAlgorithmException [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.

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.

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.

Copyright (c) 1999-2005 RSA Security Inc. All rights reserved. 038-001001-3500-001-000 - 3.5