Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.rsa.jsafe
Class JSAFE_SecretKey

java.lang.Object
  com.rsa.jsafe.JSAFE_Object
      com.rsa.jsafe.JSAFE_SecretKey

All Implemented Interfaces:: Cloneable, JSAFE_Key, Serializable

public abstract class JSAFE_SecretKey
extends JSAFE_Object
implements JSAFE_Key, Cloneable, Serializable

JSAFE_SecretKey holds and generates secret (symmetric) keys and implements the JSAFE_Key interface.

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

See Also:: Serialized Form

Field Summary

static int
ENCRYPT_KEY

static int
MAC_KEY

Method Summary

boolean
checkKeyLength(int len)

Checks whether the proposed length is valid.

void
clearSensitiveData()

This method clears sensitive data from an object.

Object
clone()

Overrides the default clone to produce a deep clone.

void
generate()

Generates key data to be held by this key object.

void
generateInit(int[] parameters, SecureRandom random)

Initializes this object to generate a key based on the given parameters using random.

void
generateReInit()

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

String
getAlgorithm()

Returns the standard algorithm name.

String
getDevice()

Returns the name of the device of record.

String[]
getDeviceList()

Returns a String array that describes all the devices used to execute the transformation.

static JSAFE_SecretKey
getInstance(String transformation, String device)

Builds an object that holds a secret key for the transformation on the given device.

byte[][]
getKeyData()

Gets the key data from the object and returns it in the default format.

byte[][]
getKeyData(String format)

Gets the key data from the object and returns it in the specified format.

String
getKeyWrappingFormat(boolean ber)

Returns the name of the format to use when getting the data for key wrapping.

int
getMaximumKeyLength()

Gets the maximum number of bits this key is allowed to have.

int
getMinimumKeyLength()

Gets the minimum number of bits this key is allowed to have.

char[]
getPassword()

Returns a new char array that contains the password.

byte[]
getSecretKeyData()

Gets the key data from the object and returns it in the default format.

byte[]
getSecretKeyData(String format)

Gets the key data from the object and returns it in the specified format.

String[]
getSupportedGetFormats()

Gets the formats in which this key can return the data.

String[]
getSupportedSetFormats()

Gets the formats with which this key may be set.

void
setKeyData(byte[][] keyData)

This method sets the key to possess the data contained in the keyData array of byte arrays.

void
setKeyData(String format, byte[][] keyData)

This method is here to fit with the JSAFE_Key interface but simply calls the other setKeyData() method.

void
setPassword(char[] newPassword, int offset, int passwordLen)

Sets this object to contain the given password.

void
setSecretKeyData(byte[] keyData, int offset, int keyDataLen)

Sets the key to possess the keyDataLen bytes of keyData, beginning at offset.

void
setSecretKeyData(String format, byte[] keyData, int offset, int keyDataLen)

Sets the key to possess the keyDataLen bytes of keyData, beginning at offset.

Methods inherited from class com.rsa.jsafe.JSAFE_Object

overwrite, overwrite

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ENCRYPT_KEY

public static final int ENCRYPT_KEY

See Also:: Constant Field Values

MAC_KEY

public static final int MAC_KEY

See Also:: Constant Field Values

Method Detail

getInstance

public static JSAFE_SecretKey getInstance(String transformation,
                                          String device)
                                   throws JSAFE_UnimplementedException

Builds an object that holds a secret key for the transformation on the given device. The value of the algorithm must be one of the following:

algorithm Values
"RC2"
"RC4"
"RC5"
"DES"
"DESX"
"3DES_EDE"
"HMAC"

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

device values
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.

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.

Parameters:: transformation - The representation of the desired operation (for example, "RC5").; device - A list of devices used to build the object (for example, "Java", "Native/Java").
Returns:: A new JSAFE_SecretKey object to use with objects that perform the transformation.
Throws:: JSAFE_UnimplementedException - If the device or devices cannot perform the designated algorithm.

getDevice

public String getDevice()

Returns the name of the device of record. The device value is as follows: "choice1[/choice2[...[/choicen]]]".

Possible device values are:

Java
Native
name of the specified hardware device

Specified by:: getDevice in interface JSAFE_Key

Returns:: The device name.

getDeviceList

public String[] 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. 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. This method returns the names of the devices used by each component.

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

getAlgorithm

public String getAlgorithm()

Returns the standard algorithm name.

Specified by:: getAlgorithm in interface JSAFE_Key

Returns:: A String that describes the algorithm.

setPassword

public void setPassword(char[] newPassword,
                        int offset,
                        int passwordLen)

Sets this object to contain the given password. This method sets the key to possess the password given by the passwordLen chars of newPassword, beginning at offset.

Parameters:: newPassword - A char array containing the characters of the password.; offset - The offset into newPassword where the data begins.; passwordLen - The length of the password (the number of chars, not the number of bytes).

getPassword

public char[] getPassword()
                   throws JSAFE_InvalidKeyException

Returns a new char array that contains the password. If the object is not set with a password, this method throws an exception.

Returns:: A char array that contains the characters of the password.
Throws:: JSAFE_InvalidKeyException - If the object is not set with a password.

getMaximumKeyLength

public int getMaximumKeyLength()

Gets the maximum number of bits this key is allowed to have.

Specified by:: getMaximumKeyLength in interface JSAFE_Key

Returns:: An int that is the maximum size, in bits, of the key.

getMinimumKeyLength

public int getMinimumKeyLength()

Gets the minimum number of bits this key is allowed to have.

Specified by:: getMinimumKeyLength in interface JSAFE_Key

Returns:: An int that is the minimum size, in bits, of the key.

getSupportedSetFormats

public String[] getSupportedSetFormats()

Gets the formats with which this key may be set.

Specified by:: getSupportedSetFormats in interface JSAFE_Key

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

getSupportedGetFormats

public String[] getSupportedGetFormats()

Gets the formats in which this key can return the data. This may be an array of length 0, if the object is not set with a key.

Specified by:: getSupportedGetFormats in interface JSAFE_Key

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

getKeyWrappingFormat

public String getKeyWrappingFormat(boolean ber)

Returns the name of the format to use when getting the data for key wrapping. Use ber to specify whether the returned data should be BER encoded or not.

Specified by:: getKeyWrappingFormat in interface JSAFE_Key

Parameters:: ber - A boolean that indicates whether the data will be wrapped BER-encoded (true) or not (false).
Returns:: A String that is the format.

setSecretKeyData

public void setSecretKeyData(String format,
                             byte[] keyData,
                             int offset,
                             int keyDataLen)
                      throws JSAFE_InvalidKeyException,
                             JSAFE_UnimplementedException

Sets the key to possess the keyDataLen bytes of keyData, beginning at offset. The format of keyData is given as the format argument. Sets the object to the data given in the specified format. Refer to setKeyData() for a description of the formats.

Parameters:: format - The format of the data being passed in.; keyData - A buffer containing the key data.; offset - The offset into keyData where the data begins.; keyDataLen - The length of the key data.
Throws:: JSAFE_InvalidKeyException - If the key data is not an appropriate length (above the maximum or below the minimum length).; JSAFE_UnimplementedException - If the object cannot set the data in the given format.
See Also:: setKeyData(java.lang.String, byte[][])

setSecretKeyData

public void setSecretKeyData(byte[] keyData,
                             int offset,
                             int keyDataLen)
                      throws JSAFE_InvalidKeyException

Sets the key to possess the keyDataLen bytes of keyData, beginning at offset. The format of keyData is assumed to be the default format. Sets the object to the data given.

Parameters:: keyData - A buffer containing the key data.; offset - The offset into keyData where the data begins.; keyDataLen - The length of the key data.
Throws:: JSAFE_InvalidKeyException - If the key data is not an appropriate length (above the maximum or below the minimum length).

setKeyData

public void setKeyData(String format,
                       byte[][] keyData)
                throws JSAFE_InvalidKeyException,
                       JSAFE_UnimplementedException

This method is here to fit with the JSAFE_Key interface but simply calls the other setKeyData() method.

Specified by:: setKeyData in interface JSAFE_Key

Parameters:: format - A String giving the format in which the data is returned.; keyData - An array of byte arrays holding the key data.
Throws:: JSAFE_UnimplementedException - If the object cannot return the data in the given format.; JSAFE_InvalidKeyException - If the key data is not an appropriate length (above the maximum or below the minimum length).

setKeyData

public void setKeyData(byte[][] keyData)
                throws JSAFE_InvalidKeyException

This method sets the key to possess the data contained in the keyData array of byte arrays. The format of keyData is assumed to be the default format, and the parameters should only be the keyData.

Specified by:: setKeyData in interface JSAFE_Key

Parameters:: keyData - An array of byte arrays holding the key data.
Throws:: JSAFE_InvalidKeyException - If the key data is not an appropriate length (above the maximum or below the minimum length).

getKeyData

public byte[][] getKeyData(String format)
                    throws JSAFE_UnimplementedException

Gets the key data from the object and returns it in the specified format.

Specified by:: getKeyData in interface JSAFE_Key

Parameters:: format - The format the data is returned in.
Returns:: An array of byte arrays containing the key data.
Throws:: JSAFE_UnimplementedException - If the object cannot return the data in the given format.

getKeyData

public byte[][] getKeyData()

Gets the key data from the object and returns it in the default format.

Specified by:: getKeyData in interface JSAFE_Key

Returns:: An array of byte arrays containing the key data.

getSecretKeyData

public byte[] getSecretKeyData(String format)
                        throws JSAFE_UnimplementedException

Gets the key data from the object and returns it in the specified format. Returns a new byte array that contains the key data in the default format.

Parameters:: format - The format the data is returned in.
Returns:: A byte array that contains the key data.
Throws:: JSAFE_UnimplementedException - If the object cannot return the data in the given format.

getSecretKeyData

public byte[] getSecretKeyData()

Gets the key data from the object and returns it in the default format.

Returns:: A byte array that contains the key data.

checkKeyLength

public boolean checkKeyLength(int len)

Checks whether the proposed length is valid.

Parameters:: len - The proposed length.
Returns:: A boolean that returns true if the length is valid, false if not.

generateInit

public void generateInit(int[] parameters,
                         SecureRandom random)
                  throws JSAFE_InvalidParameterException,
                         JSAFE_InvalidUseException

Initializes this object to generate a key based on the given parameters using random. This method initializes the key-generation process with the proper Key Generation parameters and a random number generator that generates the key bits. The key-generation process generates valid, non-weak key data.

The JSAFE_SecureRandom object is a subclass of java.security.SecureRandom, so an object of that class is valid input for random.

Parameters:: parameters - The key generating parameters, currently this can only be the length (in bits) of the key desired.; random - A SecureRandom object from which this object draws random bytes.
Throws:: JSAFE_InvalidParameterException - If the parameters given are not allowed by this algorithm (for example, 128 bits for a DES key).; JSAFE_InvalidUseException - If there is no random object.

generateReInit

public void generateReInit()
                    throws JSAFE_InvalidUseException

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

generateInit Algorithms, keyGenParameters , and keyLengthInBits

Algorithms

keyGenParameters

Value of keyLengthInBits

"RC2"

int[] params = {
keyLengthInBits
};
or null

An integer from 1 to 1024

(default value is 128)

"RC4"

int[] params = {
keyLengthInBits
};
or null

An integer from 1 to 2048

(default value is 128)

"RC5"

int[] params = {
keyLengthInBits
};
or null

An integer from 0 to 2040

(default value is 128)

"DES"

int[] params = {
keyLengthInBits
};
or null

56

"DESX"

int[] params = {
keyLengthInBits
};
or null

120

"3DES_EDE"

int[] params = {
keyLengthInBits
};
or null

168

"HMAC"

int[] params = {
keyLengthInBits
};
or null

An integer from 0 to 2048 (default value is 128)

"AES"

int[] params = {
keyLengthInBits
};
or null

128, 192 or 256

"AES128"

int[] params = {
keyLengthInBits
};
or null

128

"AES192"

int[] params = {
keyLengthInBits
};
or null

192

"AES256"

int[] params = {
keyLengthInBits
};
or null

256

generateInit Algorithms, *keyGenParameters* , and *keyLengthInBits*
Algorithms	keyGenParameters	Value of keyLengthInBits
"RC2"	int[] params = { keyLengthInBits }; or null	An integer from 1 to 1024 (default value is 128)
"RC4"	int[] params = { keyLengthInBits }; or null	An integer from 1 to 2048 (default value is 128)
"RC5"	int[] params = { keyLengthInBits }; or null	An integer from 0 to 2040 (default value is 128)
"DES"	int[] params = { keyLengthInBits }; or null	56
"DESX"	int[] params = { keyLengthInBits }; or null	120
"3DES_EDE"	int[] params = { keyLengthInBits }; or null	168
"HMAC"	int[] params = { keyLengthInBits }; or null	An integer from 0 to 2048 (default value is 128)
"AES"	int[] params = { keyLengthInBits }; or null	128, 192 or 256
"AES128"	int[] params = { keyLengthInBits }; or null	128
"AES192"	int[] params = { keyLengthInBits }; or null	192
"AES256"	int[] params = { keyLengthInBits }; or null	256

Throws:: JSAFE_InvalidUseException - If the object is not initialized for generation.

generate

public void generate()
              throws JSAFE_InvalidParameterException

Generates key data to be held by this key object. This method performs the actual key-data generation. If the keyGenParameters are not set correctly or not set at all (by an earlier call to generateInit()), this method throws an exception.

Throws:: JSAFE_InvalidParameterException - If the object is not initialized.

clone

public Object clone()
             throws CloneNotSupportedException

Overrides the default clone to produce a deep clone.

Overrides:: clone in class JSAFE_Object

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

clearSensitiveData

public void 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 should be called to perform other operations with the object.

Specified by:: clearSensitiveData in interface JSAFE_Key

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

RSA BSAFE Crypto-J 3.5.2

Method Summary
boolean	`checkKeyLength(int len)` Checks whether the proposed length is valid.
void	`clearSensitiveData()` This method clears sensitive data from an object.
Object	`clone()` Overrides the default clone to produce a deep clone.
void	`generate()` Generates key data to be held by this key object.
void	`generateInit(int[] parameters, SecureRandom random)` Initializes this object to generate a key based on the given `parameters` using `random`.
void	`generateReInit()` Re-initializes this object to generate a key with the keyGenParameters using the parameters and random objects passed in during a previous call to `generateInit()`.
String	`getAlgorithm()` Returns the standard algorithm name.
String	`getDevice()` Returns the name of the device of record.
String[]	`getDeviceList()` Returns a `String` array that describes all the devices used to execute the transformation.
static JSAFE_SecretKey	`getInstance(String transformation, String device)` Builds an object that holds a secret key for the `transformation` on the given `device`.
byte[][]	`getKeyData()` Gets the key data from the object and returns it in the default format.
byte[][]	`getKeyData(String format)` Gets the key data from the object and returns it in the specified `format`.
String	`getKeyWrappingFormat(boolean ber)` Returns the name of the format to use when getting the data for key wrapping.
int	`getMaximumKeyLength()` Gets the maximum number of bits this key is allowed to have.
int	`getMinimumKeyLength()` Gets the minimum number of bits this key is allowed to have.
char[]	`getPassword()` Returns a new `char` array that contains the password.
byte[]	`getSecretKeyData()` Gets the key data from the object and returns it in the default format.
byte[]	`getSecretKeyData(String format)` Gets the key data from the object and returns it in the specified `format`.
String[]	`getSupportedGetFormats()` Gets the formats in which this key can return the data.
String[]	`getSupportedSetFormats()` Gets the formats with which this key may be set.
void	`setKeyData(byte[][] keyData)` This method sets the key to possess the data contained in the `keyData` array of byte arrays.
void	`setKeyData(String format, byte[][] keyData)` This method is here to fit with the `JSAFE_Key` interface but simply calls the other `setKeyData()` method.
void	`setPassword(char[] newPassword, int offset, int passwordLen)` Sets this object to contain the given password.
void	`setSecretKeyData(byte[] keyData, int offset, int keyDataLen)` Sets the key to possess the `keyDataLen` bytes of `keyData`, beginning at `offset`.
void	`setSecretKeyData(String format, byte[] keyData, int offset, int keyDataLen)` Sets the key to possess the `keyDataLen` bytes of `keyData`, beginning at `offset`.

com.rsa.jsafe Class JSAFE_SecretKey

ENCRYPT_KEY

MAC_KEY

getInstance

getDevice

getDeviceList

getAlgorithm

setPassword

getPassword

getMaximumKeyLength

getMinimumKeyLength

getSupportedSetFormats

getSupportedGetFormats

getKeyWrappingFormat

setSecretKeyData

setSecretKeyData

setKeyData

setKeyData

getKeyData

getKeyData

getSecretKeyData

getSecretKeyData

checkKeyLength

generateInit

generateReInit

generateInit Algorithms, keyGenParameters , and keyLengthInBits

generate

clone

clearSensitiveData

com.rsa.jsafe
Class JSAFE_SecretKey