RSA BSAFE CRYPTO-J

Cryptographic Components for Java

JSAFE Javadoc JCE Javadoc Search

JSAFE_Parameters Class Reference

The class defines a way to hold or generate system parameters for those algorithms that require them.

Currently, Crypto-J supports the DSA and Diffie-Hellman algorithms.

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

Note: Not all Crypto-J transformations have OIDs assigned to them. See Crypto-J Transformations and Their Associated Classes for a list of transformations that have assigned OIDs.

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

Inheritance diagram for JSAFE_Parameters:

JSAFE_Object List of all members.

Public Methods

byte [] JSAFE_Parameters:: getDERAlgorithmID () throws JSAFE_UnimplementedException
 Returns a new byte array containing the DER encoding of the algorithm ID of the algorithm in this object. More...

abstract byte [] JSAFE_Parameters:: getDERAlgorithmID (String format) throws JSAFE_UnimplementedException;
 Returns a new byte array containing the DER encoding of the algorithm ID of the algorithm in this object. More...

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

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

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

abstract String [] JSAFE_Parameters:: getSupportedSetFormats ()
 Returns a String array that lists the supported formats for setParameterData(). More...

abstract String [] JSAFE_Parameters:: getSupportedGetFormats ()
 Returns a String array that lists the supported formats for getParameterData(). More...

abstract void JSAFE_Parameters:: setParameterData (String format, byte[][] parameterData) throws JSAFE_InputException, JSAFE_UnimplementedException;
 Sets an object with the parameterData in the format shown below for Diffie-Hellman and DSA algorithms. More...

abstract void JSAFE_Parameters:: setParameterData (byte[][] parameterData) throws JSAFE_InputException;
 Sets an object with the parameterData in the default format shown in the following table. More...

abstract byte [][] JSAFE_Parameters:: getParameterData (String format) throws JSAFE_UnimplementedException;
 Returns an array of byte arrays that contain the Parameterdata in the given format shown in the following table. More...

abstract byte [][] JSAFE_Parameters:: getParameterData ()
 Returns an array of byte arrays that contains the parameterData in the default format shown in the following table. More...

byte [][] JSAFE_Parameters:: getDSADomainParameterGenerationData (int[] counter) throws JSAFE_InvalidUseException
 Returns an array of byte arrays that contains the parameterData in the format shown in the following following table plus the counter value via the method argument. More...

abstract void JSAFE_Parameters:: generateInit (int[] paramGenParams, SecureRandom random) throws JSAFE_InvalidParameterException;
 Initializes this object to generate system parameters based on the given paramGenParams and using the given random. More...

abstract void JSAFE_Parameters:: generateInit (int[] paramGenParams, SecureRandom random, JSAFE_Session[] sessions) throws JSAFE_InvalidParameterException;
 Initializes this object to generate system parameters based on the given paramGenParams and using the given random. More...

void JSAFE_Parameters:: generateFIPSInit (int[] paramGenParams, SecureRandom random) throws JSAFE_InvalidParameterException, JSAFE_InvalidUseException
 Initializes this object to generate system parameters based on the given paramGenParams and using the given random. More...

abstract void JSAFE_Parameters:: generateReInit () throws JSAFE_InvalidUseException;
 Re-initializes this object to generate system parameters, using the generating parameters and the random object passed in during a previous call to generateInit(). More...

abstract void JSAFE_Parameters:: generate () throws JSAFE_InvalidUseException;
 Generates the system parameters to be held by this object. More...

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

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


Static Public Methods

JSAFE_Parameters JSAFE_Parameters:: getInstance (byte[] berAlgID, int offset, String device) throws JSAFE_UnimplementedException, JSAFE_InvalidParameterException
 Builds an object that contains the parameters defined in berAlgID, beginning at offset. More...

int JSAFE_Parameters:: getNextBEROffset (byte[] berAlgID, int offset) throws JSAFE_UnimplementedException
 Computes the offset into berAlgID for the byte immediately following the algorithm ID, which begins at offset. More...

JSAFE_Parameters JSAFE_Parameters:: getInstance (String transformation, String device) throws JSAFE_UnimplementedException, JSAFE_InvalidParameterException
 Builds an object that performs the transformation on the given device. More...

Member Function Documentation

void JSAFE_Parameters::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.

Reimplemented from JSAFE_Object.

abstract Object JSAFE_Parameters::clone (    )  throws CloneNotSupportedException; [inline, pure virtual];
 

Overrides the default clone to produce a deep clone.

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

Reimplemented from JSAFE_Object.

abstract void JSAFE_Parameters::generate (    )  throws JSAFE_InvalidUseException; [inline, pure virtual];
 

Generates the system parameters to be held by this object.

Exceptions:
JSAFE_InvalidUseException If the object is not initialized.

void JSAFE_Parameters::generateFIPSInit (  int    paramGenParams[],
SecureRandom    random
)  throws JSAFE_InvalidParameterException, JSAFE_InvalidUseException [inline];
 

Initializes this object to generate system parameters based on the given paramGenParams and using the given random. Sets the generation method to follow the FIPS prescription. The JSAFE_SecureRandom object is a subclass of SecureRandom object, so it is valid input.

This method is provided for backward compatibility and is not necesary. Since Crypto-J 3.5 the preferred method is to call generateInit(), passing a "FIPS186Random" and to set the library to FIPS_MODE.

Algorithm paramGenParams Values
"Diffie-Hellman"int[] primeLen is the length of the prime in bits,
paramGenParams = {which is a value from 256 to 2048.
primeLen, maxExponentLen is the maximum length of the
maxExponentLen private exponent (also known as the private
}; value), a value less than primeLen and greater
than or equal to 160.
"DSA" int[] primeLen is the length of the prime in bits,
paramGenParams = {which is a value from 256 to 4096.
primeLen,
};

See also:
generateInit
Parameters:
paramGenParams The generating parameters, such as a length value.
random A SecureRandom object from which this object draws random bytes if necessary.
Exceptions:
JSAFE_InvalidParameterException If the given generating parameters are not allowed by this algorithm (for example, 128 bits for DSA parameters).
JSAFE_InvalidUseException If this method is used when no special FIPS method was implemented.

abstract void JSAFE_Parameters::generateInit (  int    paramGenParams[],
SecureRandom    random,
JSAFE_Session    sessions[]
)  throws JSAFE_InvalidParameterException; [inline, pure virtual];
 

Initializes this object to generate system parameters based on the given paramGenParams and using the given random. The JSAFE_SecureRandom object is a subclass of SecureRandom, so it is valid input. The sessions argument is an array of hardware sessions. Crypto-J passes these sessions on to the devices specified in the getInstance call. The devices use or ignore the sessions as necessary.

Since:
3.2
Algorithm paramGenParams Values
"Diffie-Hellman"int[] primeLen is the length of the prime in bits,
paramGenParams = {which is a value from 256 to 2048.
primeLen, maxExponentLen is the maximum length of the
maxExponentLen private exponent (also known as the private
}; value), a value less than primeLen and greater
than or equal to 160.
"DSA" int[] primeLen is the length of the prime in bits,
paramGenParams = {which is a value from 256 to 4096.
primeLen,
};

Parameters:
paramGenParams The generating parameters, such as a length value.
random A SecureRandom object from which this object draws random bytes if necessary.
sessions An array of JSAFE_Session objects from which the object draws its implementation.
Exceptions:
JSAFE_InvalidParameterException If the given generating parameters are not allowed by this algorithm (for example, 128 bits for DSA parameters).

abstract void JSAFE_Parameters::generateInit (  int    paramGenParams[],
SecureRandom    random
)  throws JSAFE_InvalidParameterException; [inline, pure virtual];
 

Initializes this object to generate system parameters based on the given paramGenParams and using the given random. The JSAFE_SecureRandom object is a subclass of java.security.SecureRandom, so an object of that class is valid input for random.

Algorithm paramGenParams Values
"Diffie-Hellman"int[] primeLen is the length of the prime in bits,
paramGenParams = {which is a value from 256 to 2048.
primeLen, maxExponentLen is the maximum length of the
maxExponentLen private exponent (also known as the private
}; value), a value less than primeLen and greater
than or equal to 160.
"DSA" int[] primeLen is the length of the prime in bits,
paramGenParams = {which is a value from 256 to 4096.
primeLen,
};

Parameters:
paramGenParams The generating parameters, such as a length value.
random A SecureRandom object from which this object draws random bytes if necessary.
Exceptions:
JSAFE_InvalidParameterException If the given generating parameters are not allowed by this algorithm (for example, 128 bits for DSA parameters).

abstract void JSAFE_Parameters::generateReInit (    )  throws JSAFE_InvalidUseException; [inline, pure virtual];
 

Re-initializes this object to generate system parameters, using the generating parameters and the random object passed in during a previous call to generateInit().

Exceptions:
JSAFE_InvalidUseException If the object is not initialized for generation.

abstract String JSAFE_Parameters::getAlgorithm (    )  [pure virtual];
 

Returns the standard algorithm name.

Returns:
A String that describes the algorithm.

abstract byte [] JSAFE_Parameters::getDERAlgorithmID (  String    format )  throws JSAFE_UnimplementedException; [inline, pure virtual];
 

Returns a new byte array containing the DER encoding of the algorithm ID of the algorithm in this object. Uses the OID for the given format parameter. Refer to the Crypto-J Developer's Guide for more information on the different OIDs.

The possible values for format are:
format values Cryptography Standard
DSAParametersBER (follows X9.30)
DSAParametersX957BER (follows X9.57) 

 Note:  For Diffie_Hellman parameters, either pass in null for the
        format parameter, or use the getDERAlgorithmID method that does not take
        arguments. For DSA parameters, the getDERAlgorithmID method is called
        without a format argument, resulting in a parameter algorithm
        ID that follows X9.30.
Parameters:
format The standard to follow (for example, "DSAParametersX957BER").
Returns:
A new byte array that contains the algorithm ID.
Exceptions:
JSAFE_UnimplementedException If the algorithm has no OID, or if there is not enough information to build the algorithm ID.

byte [] JSAFE_Parameters::getDERAlgorithmID (    )  throws JSAFE_UnimplementedException [inline];
 

Returns a new byte array containing the DER encoding of the algorithm ID of the algorithm in this object.

Returns:
A new byte array that contains the algorithm ID.
Exceptions:
JSAFE_UnimplementedException If the algorithm has no OID, or there is not enough information to build the algorithm ID.

String JSAFE_Parameters::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_Parameters::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. A device can perform one or more of the algorithms, but it may let Java or another device perform one or more. For example, because padding is not time-consuming, a device might let the Crypto-J implementation perform padding. Returns the names of the devices used by each component.

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

byte [][] JSAFE_Parameters::getDSADomainParameterGenerationData (  int    counter[] )  throws JSAFE_InvalidUseException [inline];
 

Returns an array of byte arrays that contains the parameterData in the format shown in the following following table plus the counter value via the method argument.

This method supports the DSAVS Domain Parameter Generation test. It enables the test to retrive the DSA parameters P, Q, G, H, seed, and counter.

Algorithm Supported Formats parameterData
"DSA" "DSAParameters" byte[][] paramData = {
(default) prime,
subPrime,
base,
hArray,
seed
};

Returns:
An array of byte arrays that contain the parameter data, P, Q, G, and H, plus the counter in the argument.
Exceptions:
JSAFE_InvalidUseException If the algorithm is not DSA or the library is not on FIPS_MODE.

JSAFE_Parameters JSAFE_Parameters::getInstance (  String    transformation,
String    device
)  throws JSAFE_UnimplementedException, JSAFE_InvalidParameterException [inline, static];
 

Builds an object that performs the transformation on the given device. Currently, Crypto-J supports two algorithms (Diffie-Hellman and DSA) that need this class.

The value of algorithm is as follows:

  • "DH" (Diffie-Hellman)
  • "DSA"

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

  • Java
  • Native
  • name of specified hardware device
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. Refer to the "Cryptographic Hardware" section
       in the Crypto-J Developer’s Guide , which describes hardware usage,
       its benefits, and its problems.

 For example:
   JSAFE_Parameters dhParams = JSAFE_Parameters.getInstance
       ("DH", "Acme/Native/Java");
Parameters:
transformation The representation of the desired operation (for example, "DH" or "DSA").
device A list of devices used to build the object (for example, "Java", "Native/Java", or name of specified hardware device).
Returns:
A new JSAFE_Parameters object to use with objects that perform the transformation.
Exceptions:
JSAFE_UnimplementedException If the device or devices cannot perform the designated algorithm.
JSAFE_InvalidParameterException If the transformation contains parameters that do not work.

JSAFE_Parameters JSAFE_Parameters::getInstance (  byte    berAlgID[],
int    offset,
String    device
)  throws JSAFE_UnimplementedException, JSAFE_InvalidParameterException [inline, static];
 

Builds an object that contains the parameters defined in berAlgID, beginning at offset. The specified device is used.

The value encoded in berAlgID must follow the definition defined in X.509: 

   AlgorithmIdentifier ::= SEQUENCE {
     algorithm OBJECT IDENTIFIER,
     parameters ANY DEFINED BY algorithm OPTIONAL }
The Diffie-Hellman algorithm identifier follows the definition below: 
   AlgorithmIdentifier ::= SEQUENCE {
     algorithm OBJECT IDENTIFIER, -- { pkcs-3 1 }
     SEQUENCE {
       prime INTEGER, -- p
       base  INTEGER, -- g
       privateValueLength INTEGER OPTIONAL } }
The DSA algorithm identifier must use one of the following ASN.1 definitions: 
 DSA AlgorithmIdentifier According to X9.30
   AlgorithmIdentifier ::= SEQUENCE {
     algorithm OBJECT IDENTIFIER,
     SEQUENCE {
       modulusLength INTEGER,
       prime         INTEGER,
       subPrime      INTEGER,
       base          INTEGER } }

 DSA AlgorithmIdentifier According to X9.57
   AlgorithmIdentifier ::= SEQUENCE {
     algorithm OBJECT IDENTIFIER,
     SEQUENCE {
       prime         INTEGER,
       subPrime      INTEGER,
       base          INTEGER } }
Parameters:
berAlgID The BER encoding of the algorithm identifier.
offset The starting point of the BER encoding.
device A list of devices to use when building the object (for example, "Java", "Native/Java", or name of specified hardware device).
Returns:
A new JSAFE_Parameters object.
Exceptions:
JSAFE_UnimplementedException If the device or devices cannot perform the designated algorithm.
JSAFE_InvalidParameterException If the BER contains parameters that do not work.

int JSAFE_Parameters::getNextBEROffset (  byte    berAlgID[],
int    offset
)  throws JSAFE_UnimplementedException [inline, static];
 

Computes the offset into berAlgID for the byte immediately following the algorithm ID, which begins at offset. Given the BER encoding of the algorithm ID, returns the index to the next byte in the array. Gets the next offset after the algorithm ID.

Parameters:
berAlgID A byte array containing the BER encoding of an algorithm ID.
offset The offset into berAlgID where the encoding begins.
Returns:
The index into berAlgID of the byte following the algorithm ID.
Exceptions:
JSAFE_UnimplementedException If the toolkit cannot decode the BER encoding.

abstract byte [][] JSAFE_Parameters::getParameterData (    )  [pure virtual];
 

Returns an array of byte arrays that contains the parameterData in the default format shown in the following table.

Algorithm Supported Formats parameterData
"Diffie-Hellman" "DHParameters" byte[][] paramData = {
(default) prime,
base,
maxExponentLen,
};
"DHParametersBER" byte[] algorithmID;
byte[][] paramData = {
algorithmID
};
"DSA" "DSAParameters" byte[][] paramData = {
(default) prime,
subPrime,
base,
};
"DSAParametersX957BER" byte[] algorithmID;
"DSAParametersBER" byte[][] paramData = {
algorithmID
};

Returns:
An array of byte arrays that contain the parameter data.

abstract byte [][] JSAFE_Parameters::getParameterData (  String    format )  throws JSAFE_UnimplementedException; [inline, pure virtual];
 

Returns an array of byte arrays that contain the Parameterdata in the given format shown in the following table.

Algorithm Supported Formats parameterData
"Diffie-Hellman" "DHParameters" byte[][] paramData = {
(default) prime,
base,
maxExponentLen,
};
"DHParametersBER" byte[] algorithmID;
byte[][] paramData = {
algorithmID
};
"DSA" "DSAParameters" byte[][] paramData = {
(default) prime,
subPrime,
base,
};
"DSAParametersX957BER" byte[] algorithmID;
"DSAParametersBER" byte[][] paramData = {
algorithmID
};

Note: If the format is DSAParametersBER, the resulting algorithm ID follows X9.30.

Parameters:
format The format in which the data is returned.
Returns:
An array of byte arrays that contain the parameter data.
Exceptions:
JSAFE_UnimplementedException If the object cannot return the data in the given format.

abstract String [] JSAFE_Parameters::getSupportedGetFormats (    )  [pure virtual];
 

Returns a String array that lists the supported formats for getParameterData(). The return value can be a zero-length array if the object is not yet set.

Returns:
A String array, that is the list of valid formats.

abstract String [] JSAFE_Parameters::getSupportedSetFormats (    )  [pure virtual];
 

Returns a String array that lists the supported formats for setParameterData().

Returns:
A String array that is the list of valid formats.

abstract void JSAFE_Parameters::setParameterData (  byte    parameterData[][] )  throws JSAFE_InputException; [inline, pure virtual];
 

Sets an object with the parameterData in the default format shown in the following table.

Algorithm Supported Formats parameterData
"Diffie-Hellman" "DHParameters" byte[][] paramData = {
(default) prime,
base,
maxExponentLen,
};
"DHParametersBER" byte[] algorithmID;
byte[][] paramData = {
algorithmID
};
"DSA" "DSAParameters" byte[][] paramData = {
(default) prime,
subPrime,
base,
};
"DSAParametersX957BER" byte[] algorithmID;
"DSAParametersBER" byte[][] paramData = {
algorithmID
};

Note: If the format is DSAParametersBER, the resulting algorithm ID follows X9.30.

Parameters:
parameterData An array of byte arrays containing the actual data.
Exceptions:
JSAFE_InputException If the data is not of the appropriate algorithm.

abstract void JSAFE_Parameters::setParameterData (  String    format,
byte    parameterData[][]
)  throws JSAFE_InputException, JSAFE_UnimplementedException; [inline, pure virtual];
 

Sets an object with the parameterData in the format shown below for Diffie-Hellman and DSA algorithms.

Algorithm Supported Formats parameterData
"Diffie-Hellman" "DHParameters" byte[][] paramData = {
(default) prime,
base,
maxExponentLen,
};
"DHParametersBER" byte[] algorithmID;
byte[][] paramData = {
algorithmID
};
"DSA" "DSAParameters" byte[][] paramData = {
(default) prime,
subPrime,
base,
};
"DSAParametersX957BER" byte[] algorithmID;
"DSAParametersBER" byte[][] paramData = {
algorithmID
};

Note: If the format is DSAParametersBER, the resulting algorithm ID follows X9.30.

Parameters:
format The format of the data being passed in.
parameterData An array of byte arrays containing the actual data.
Exceptions:
JSAFE_InputException If the data is not of the appropriate algorithm.
JSAFE_UnimplementedException If the object cannot set the data in the given format.

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