	RSA BSAFE CRYPTO-J	Cryptographic Components for Java
JSAFE Javadoc	JCE Javadoc	Search

JSAFE_KeyPair Class Reference

JSAFE_KeyPair defines low-level key management and generation routines for a particular algorithm and can instantiate the classes that hold and generate public/private key pairs.

Define the higher-level key management in external classes (such as certification authorities).

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

Inheritance diagram for JSAFE_KeyPair:

List of all members.

Public Methods
void JSAFE_KeyPair::	setPrivateKeyAttributes (JSAFE_KeyAttributes attributes)
	Sets the in-token attributes of the private key. More...
void JSAFE_KeyPair::	setPublicKeyAttributes (JSAFE_KeyAttributes attributes)
	Sets the in-token attributes of the public key. More...
String JSAFE_KeyPair::	getDevice ()
	Returns the name of the device of record. More...
String [] JSAFE_KeyPair::	getDeviceList ()
	Returns a `String` array that describes all the devices used to execute the transformation. More...
abstract String JSAFE_KeyPair::	getAlgorithm ()
	Returns the standard algorithm name. More...
void JSAFE_KeyPair::	setKeys (JSAFE_PublicKey pubKey, JSAFE_PrivateKey priKey) throws JSAFE_InvalidKeyException
	Copies the public and private keys into this object. More...
JSAFE_PublicKey JSAFE_KeyPair::	getPublicKey ()
	Returns a copy of the public key portion of a key pair as a `JSAFE_PublicKey` object. More...
JSAFE_PrivateKey JSAFE_KeyPair::	getPrivateKey ()
	Returns a copy of the private key portion of a key pair as a `JSAFE_PrivateKey` object. More...
Object JSAFE_KeyPair::	clone () throws CloneNotSupportedException
	Overrides the default clone to produce a deep clone. More...
void JSAFE_KeyPair::	generateInit (JSAFE_Parameters sharedParameters, int[] keyPairGenParameters, SecureRandom random) throws JSAFE_InvalidParameterException, JSAFE_InvalidUseException
	Initializes this object to generate a key pair. More...
void JSAFE_KeyPair::	generateInit (JSAFE_Parameters sharedParameters, int[] keyPairGenParameters, SecureRandom random, JSAFE_Session[] sessions) throws JSAFE_InvalidParameterException, JSAFE_InvalidUseException
	Initializes this object to generate a key pair. More...
void JSAFE_KeyPair::	generateStrongInit (JSAFE_Parameters sharedParameters, int[] keyPairGenParameters, SecureRandom random) throws JSAFE_InvalidParameterException, JSAFE_InvalidUseException
	Initializes this object to generate a key pair, using techniques to guarantee the use of only strong primes. More...
void JSAFE_KeyPair::	generateReInit () throws JSAFE_InvalidUseException
	Re-initializes this object to generate a key pair, using the parameters and the random object passed in during a previous call to `generateInit()`. More...
byte [][] JSAFE_KeyPair::	generateKeyPair (byte[] xp1, byte[] xp2, byte[] Xp, byte[] xq1, byte[] xq2, byte[] Xq) throws JSAFE_InvalidUseException
	Generates a strong key pair for testing according to the RSA Validation System. More...
void JSAFE_KeyPair::	generate () throws JSAFE_InvalidUseException
	Generates the key pair. More...
void JSAFE_KeyPair::	clearSensitiveData ()
	This method clears sensitive data from an object. More...
Static Public Methods
JSAFE_KeyPair JSAFE_KeyPair::	getInstance (String transformation, String device) throws JSAFE_UnimplementedException, JSAFE_InvalidParameterException
	Builds a `JSAFE_KeyPair` object that holds and generates key pairs of type `transformation` on the given `device`. More...

Member Function Documentation

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

Object JSAFE_KeyPair::clone ( ) throws CloneNotSupportedException [inline];

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.

void JSAFE_KeyPair::generate ( ) throws JSAFE_InvalidUseException [inline];

Generates the key pair.

Exceptions:

JSAFE_InvalidUseException If the object is not initialized for key-pair generation.

void JSAFE_KeyPair::generateInit ( JSAFE_Parameters sharedParameters,

int keyPairGenParameters[],

SecureRandom random,

JSAFE_Session sessions[]

) throws JSAFE_InvalidParameterException, JSAFE_InvalidUseException [inline];

Initializes this object to generate a key pair. If the algorithm needs system parameters, pass them in as sharedParameters. If not, that argument should be null. If the algorithm needs only key-generating parameters, pass in the appropriate keyPairGenParameters. If not, that argument should be null. Any random bytes the object needs will come from random.
The JSAFE_SecureRandom object is a subclass of java.security.SecureRandom, so an object of that class is valid input for random.
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.

Parameters:

sharedParameters System parameters, if needed.

keyPairGenParameters The key-pair generating parameters (such as key size), if needed.

random A SecureRandom object from which this object draws random bytes.

sessions An array of JSAFE_Session objects from which this object will draw its implementation.

Exceptions:

JSAFE_InvalidParameterException If the system or key-pair generating parameters are inappropriate (such as a key size that is too small or too large).

JSAFE_InvalidUseException If required system parameters are not passed in.

void JSAFE_KeyPair::generateInit ( JSAFE_Parameters sharedParameters,

int keyPairGenParameters[],

SecureRandom random

) throws JSAFE_InvalidParameterException, JSAFE_InvalidUseException [inline];

Initializes this object to generate a key pair. If the algorithm needs system parameters, pass them in as sharedParameters. If not, that argument should be null. If the algorithm needs only key-generating parameters, pass in the appropriate keyPairGenParameters. If not, that argument should be null. Any random bytes the object needs will come from random.
JSAFE_SecureRandom is a subclass of java.security.SecureRandom, so an object of that class is valid input for random.
The following table summarizes the JSAFE_KeyPair parameters that are used for the RSA, Diffie-Hellman, and DSA algorithms: sharedParameters and keyPairGenParameters for RSA, DH, and DSA.
Algorithm sharedParameters keyPairGenParameters

"RSA" null int[] KeyPairGenParams = {modulusBits, publicExponent };

modulusBits is the length of the modulus in bits, a value from 256 to 4096.

publicExponent is generally a Fermat number: for example, 3,17, or 65537.

"RSA"
(MultiPrime) null int[] KeyPairGenParams = {modulusBits, numberOfPrimes, publicExponent };

modulusBits is the length of the modulus in bits, a value from 256 to 4096, if numberOfPrimes is 2, or from 1024 to 4096, if numberOfPrimes is 3.

numberOfPrimes describes how many primes make up the modulus, a value of 2 or 3.

publicExponent is generally a Fermat number: for example, 3,17, or 65537.

Diffie-Hellman JSAFE_Parameters object null

DSA JSAFE_Parameters object null

Since:
3.2
Parameters:

sharedParameters System parameters, if needed.

keyPairGenParameters The key-pair generating parameters (such as key size), if needed.

random A SecureRandom object from which this object draws random bytes.

Exceptions:

JSAFE_InvalidParameterException If the system or key-pair generating parameters are inappropriate (such as a key size that is too small or too large).

JSAFE_InvalidUseException If required system parameters are not passed in.

byte [][] JSAFE_KeyPair::generateKeyPair ( byte xp1[],

byte xp2[],

byte Xp[],

byte xq1[],

byte xq2[],

byte Xq[]

) throws JSAFE_InvalidUseException [inline];

Generates a strong key pair for testing according to the RSA Validation System.

Parameters:

xp1 starting point for finding subprime p1, a factor of p-1

xp2 starting point for finding subprime p2, a factor of p+1

Xp starting point for finding prime p, a factor of n=p*q

xq1 starting point for finding subprime q1, a factor of q-1

xq2 starting point for finding subprime q2, a factor of q+1

Xq starting point for finding prime q, a factor of n=p*q

Returns:
an array of byte arrays with data required by the RSAVS (p1, p2, p, q1, q2, q, n, and d).
Exceptions:

JSAFE_InvalidUseException If the object is not initialized for key-pair generation, the library is not in FIPS mode or the user is not the CRYPTO officer.

void JSAFE_KeyPair::generateReInit ( ) throws JSAFE_InvalidUseException [inline];

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

Exceptions:

JSAFE_InvalidUseException If the object is not initialized for key-pair generation.

void JSAFE_KeyPair::generateStrongInit ( JSAFE_Parameters sharedParameters,

int keyPairGenParameters[],

SecureRandom random

) throws JSAFE_InvalidParameterException, JSAFE_InvalidUseException [inline];

Initializes this object to generate a key pair, using techniques to guarantee the use of only strong primes. If the algorithm needs system parameters, pass them in as sharedParameters. If not, that argument should be null. If the algorithm needs key-generating parameters, pass in the appropriate keyPairGenParameters. If not, that argument should be null. Any random bytes the object needs will come from random.
JSAFE_SecureRandom is a subclass of java.security.SecureRandom, so an object of that class is valid input for random.
If the algorithm does not support strong key-pair generation, this method will throw an exception. Currently, Crypto-J supports strong key-pair generation only with the RSA algorithm.
After initializing with this method, generation will utilize prime-finding techniques that guarantee strong primes. The other key-pair generation code is faster, but it may produce weak primes. Note that the probability of producing weak primes is extremely low.
The key pairs generated from this method conform to the X9.31 standard.
This method requires a hardware random number generator or a JSAFE_SecureRandom set to perform X931Random. If any other PRNG (SecureRandom or JSAFE_SecureRandom set to MD5Random or SHA1Random) is passed in, this method will throw an exception.

Parameters:

sharedParameters System parameters, if needed (none are needed for RSA).

keyPairGenParameters The key-pair generating parameters (such as key size), if needed. For RSA there should be either one parameter (modulusLen), two parameters (modulusLen and public exponent) or three parameters (modulusLen, numberOfPrimes and publicExponent).

random A SecureRandom object from which this object will draw random bytes.

Exceptions:

JSAFE_InvalidParameterException If the system or key-pair generating parameters are inappropriate (such as a key size that is too small or too large).

JSAFE_InvalidUseException If required system parameters are not passed in.

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

Returns the standard algorithm name.

Returns:
A String describing the algorithm.

String JSAFE_KeyPair::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_KeyPair::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.

JSAFE_KeyPair JSAFE_KeyPair::getInstance ( String transformation,

String device

) throws JSAFE_UnimplementedException, JSAFE_InvalidParameterException [inline, static];

Builds a JSAFE_KeyPair object that holds and generates key pairs of type transformation on the given device.

Parameters:

transformation The representation of the desired operation. The value of algorithm must be one of the following: "RSA", "DH" (Diffie-Hellman), or "DSA".

device A list of devices used to build the object. The device value is as follows: "choice1[/choice2[...[/choicen]]]", where the choices for device value are: Java, Native, name of the specified hardware device. Crypto-J tries to instantiate a class using the first choice; if it cannot, it tries the other choices.

Returns:
A new JSAFE_KeyPair object to use with objects that perform the algorithm.
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_PrivateKey JSAFE_KeyPair::getPrivateKey ( ) [inline];

Returns a copy of the private key portion of a key pair as a JSAFE_PrivateKey object. If this object does not contain a private key, this method returns null.

Returns:
The JSAFE_PrivateKey inside this object.

JSAFE_PublicKey JSAFE_KeyPair::getPublicKey ( ) [inline];

Returns a copy of the public key portion of a key pair as a JSAFE_PublicKey object. If this object does not contain a public key, this method returns null.

Returns:
The JSAFE_PublicKey inside this object.

void JSAFE_KeyPair::setKeys ( JSAFE_PublicKey pubKey,

JSAFE_PrivateKey priKey

) throws JSAFE_InvalidKeyException [inline];

Copies the public and private keys into this object. This method sets an object with pubKey and priKey. Crypto-J stores new copies of the keys in this JSAFE_keyPair object.

Parameters:

pubKey The public key to copy.

priKey The private key to copy.

Exceptions:

JSAFE_InvalidKeyException If the keys do not match the algorithm.

void JSAFE_KeyPair::setPrivateKeyAttributes ( JSAFE_KeyAttributes attributes ) [inline];

Sets the in-token attributes of the private key.

Parameters:

attributes A JSAFE_KeyAttributes instance.

void JSAFE_KeyPair::setPublicKeyAttributes ( JSAFE_KeyAttributes attributes ) [inline];

Sets the in-token attributes of the public key.

Parameters:

attributes A JSAFE_KeyAttributes instance.

JSAFE_KeyPair Class Reference

Public Methods

Static Public Methods

Member Function Documentation