com.rsa.jsafe.JSAFE_Object
com.rsa.jsafe.JSAFE_KeyAgree
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Object
The JSAFE_KeyAgree class defines the factory method and API
for the key agreement algorithms. This class can instantiate the classes
that perform key agreement and defines the functionality.
Currently, Crypto-J only supports Diffie-Hellman key agreement.
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.
| Constructor Summary | |
JSAFE_KeyAgree()
|
|
| Method Summary | |
void |
clearSensitiveData()
This method clears sensitive data from an object. |
abstract JSAFE_PublicKey |
generateMyPublicValue()
Generates the public value, using key-based key agreement
methods in the form of |
byte[] |
generateSharedSecret()
Computes the shared secret and returns it in a new |
abstract int |
generateSharedSecret(byte[] sharedSecret,
int offset)
Computes the shared secret and places it in the
|
byte[] |
generateSharedSecret(JSAFE_PublicKey correspondentKey)
Computes the shared secret and returns it in a new |
abstract int |
generateSharedSecret(JSAFE_PublicKey correspondentKey,
byte[] sharedSecret,
int offset)
Computes the shared secret and places it in the byte
array |
getBlankKeyPair()
Returns a new, empty |
|
abstract byte[] |
getDERAlgorithmID()
Returns a new |
getDevice()
Returns the name of the device of record. |
|
String[] |
getDeviceList()
Returns a |
static JSAFE_KeyAgree |
getInstance(byte[] berAlgID,
int offset,
String device)
Builds an object that performs an algorithm using the possible
parameters defined in |
static JSAFE_KeyAgree |
getInstance(String transformation,
String device)
Builds an object that performs the specified |
abstract String |
getKeyAgreeAlgorithm()
Returns the standard name of the key agreement algorithm. |
static int |
getNextBEROffset(byte[] berAlgID,
int offset)
Gets the next offset after the algorithm ID. |
abstract int |
getOutputSize()
Returns the output size (in bytes) that results from a key-agreement operation. |
byte[] |
getPrivateValue()
Retrieves the private value in a new |
abstract int |
getPrivateValue(byte[] privateValue,
int offset)
Retrieves the private value. |
abstract JSAFE_PrivateKey |
getPrivateValueAsKey()
Returns a new |
abstract JSAFE_Parameters |
getSharedParameters()
Returns a new |
abstract void |
keyAgreeInit(JSAFE_Parameters sharedParameters,
JSAFE_PrivateKey myKey,
SecureRandom random)
Initializes an object to compute key-agreement values
using |
abstract void |
keyAgreeInit(JSAFE_Parameters sharedParameters,
JSAFE_PublicKey correspondentKey,
SecureRandom random)
Initializes an object to compute key-agreement values
using |
abstract void |
keyAgreeInit(JSAFE_Parameters sharedParameters,
SecureRandom random)
Initializes an object to compute key-agreement values using
|
abstract void |
keyAgreeInit(JSAFE_PrivateKey myKey,
SecureRandom random)
Initializes this object for key agreement using the private key
specified by |
abstract void |
keyAgreeInit(JSAFE_PublicKey correspondentKey,
SecureRandom random)
Initializes an object to compute key-agreement values using
|
abstract void |
keyAgreeInit(SecureRandom random)
Initializes an object to compute the key-agreement values using the parameters that were already loaded into an object. |
byte[] |
keyAgreePhase1()
Performs Phase 1 of key agreement, generating a public value. |
abstract int |
keyAgreePhase1(byte[] myPublicValue,
int offset)
Performs Phase 1 of key agreement, generating a public value. |
byte[] |
keyAgreePhase2(byte[] correspondentPublicValue,
int offset,
int len)
Performs Phase 2 of key agreement, generating the shared secret, using
the private value generated during |
abstract int |
keyAgreePhase2(byte[] correspondentPublicValue,
int inOffset,
int len,
byte[] sharedSecret,
int outOffset)
Performs Phase 2 of key agreement, computing the shared secret and placing
it in the byte array |
abstract void |
keyAgreeReInit()
Re-initializes the object to perform key agreement. |
| Methods inherited from class com.rsa.jsafe.JSAFE_Object |
clone, overwrite, overwrite |
| Methods inherited from class java.lang.Object |
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Constructor Detail |
public JSAFE_KeyAgree()
| Method Detail |
public static JSAFE_KeyAgree getInstance(byte[] berAlgID, int offset, String device) throws JSAFE_UnimplementedException, JSAFE_InvalidParameterException
berAlgID. This is the BER encoding
of the algorithm identifier. The specified device is used. The
value encoded in berAlgID always follows the definition
listed below.
AlgorithmIdentifier ::=SEQUENCE {
algorithm OBJECT IDENTIFIER,
parameters ANY DEFINED BY algorithm OPTIONAL}
berAlgID - A byte array containing the BER encoding of
an algorithm ID.offset - The offset into berAlgID where the encoding
begins.device - A list of devices used to build the object.
JSAFE_KeyAgree object that performs the
transformation as described by the algorithm ID.
JSAFE_UnimplementedException - If the device or devices cannot
perform the designated algorithm, or if the toolkit cannot decode
the BER encoding.
JSAFE_InvalidParameterException - If the BER encoding contains
parameters that do not work.
public static int getNextBEROffset(byte[] berAlgID,
int offset)
throws JSAFE_UnimplementedException
berAlgID, the BER encoding of the algorithm ID,
beginning at offset, returns the index to the next
byte in the array.
berAlgID - A byte array containing the BER encoding
of an algorithm ID.offset - The offset into berAlgID where the encoding
begins.
berAlgID of the byte following the
algorithm ID.
JSAFE_UnimplementedException - If the toolkit cannot decode the
BER encoding.public static JSAFE_KeyAgree getInstance(String transformation, String device) throws JSAFE_UnimplementedException, JSAFE_InvalidParameterException
transformation
on the given device. The value of the algorithm is
"DH".
The device value is as follows:
"choice1[/choice2[...[/choicen]]]" where the choices are:
transformation - The representation of the desired operation
(for example, "DH").device - A list of devices to use when building the object
(for example, "Java", "Native/Java").
JSAFE_KeyAgree object that performs the
transformation.
JSAFE_UnimplementedException - If the device or devices cannot
perform the designated algorithm.
JSAFE_InvalidParameterException - If the
transformation contains parameters that do not work.
public abstract byte[] getDERAlgorithmID()
throws JSAFE_UnimplementedException
byte array containing the DER encoding
of the key agreement algorithm identifier of the algorithm in this object.
byte array that contains the algorithm ID.
JSAFE_UnimplementedException - If the algorithm has no OID,
or there is not enough information to build the algorithm ID.public String getDevice()
public String[] getDeviceList()
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.
String array that describes the device used for a
specific component.public abstract String getKeyAgreeAlgorithm()
String that describes the key agreement algorithm.public abstract JSAFE_Parameters getSharedParameters() throws JSAFE_InvalidUseException
JSAFE_Parameters object that contains the
shared-key agreement parameters. If an object does not yet contain
parameters, this method throws an exception.
Gets the system parameters, if any.
JSAFE_Parameters object that contains the
system parameters.
JSAFE_InvalidUseException - If the object contains no
system parameters.public JSAFE_KeyPair getBlankKeyPair()
JSAFE_KeyPair object to match the
algorithm and device of this object.
This key-pair object may then be used to set or generate the key data.
JSAFE_KeyPair object.public abstract int getOutputSize()
keyAgreeInit(), or at instantiation in the
BER encoding of an algorithm identifier).
Otherwise, the return value could be zero.
int that is the size of the output.public abstract void keyAgreeInit(SecureRandom random) throws JSAFE_InvalidUseException
keyAgreeInit() was previously called.
If an algorithm needs random bytes, the object gets them from
random. JSAFE_SecureRandom
is a subclass of java.security.SecureRandom, so an object of
that class is valid input for random.
random - A SecureRandom object from which this object
draws random bytes, if necessary.
JSAFE_InvalidUseException - If the object does not yet possess
system parameters.public abstract void keyAgreeInit(JSAFE_Parameters sharedParameters, SecureRandom random) throws JSAFE_InvalidParameterException, JSAFE_InvalidUseException
sharedParameters. If an algorithm needs random bytes,
an object gets them from random.
JSAFE_SecureRandom is a subclass of
java.security.SecureRandom, so an object of that class is
valid input for random.
sharedParameters - A JSAFE_Parameters object containing
the system parameters.random - A SecureRandom object from which this object
draws random bytes, if necessary.
JSAFE_InvalidParameterException - If the shared parameters
do not match the algorithm specified at instantiation.
JSAFE_InvalidUseException - If the object does not possess a
random object.public abstract void keyAgreeInit(JSAFE_Parameters sharedParameters, JSAFE_PublicKey correspondentKey, SecureRandom random) throws JSAFE_InvalidParameterException, JSAFE_InvalidKeyException, JSAFE_InvalidUseException
Initializes an object to compute key-agreement values
using sharedParameters and correspondentKey.
If an algorithm needs random bytes, an object gets them from
random. JSAFE_SecureRandom is a subclass of
java.security.SecureRandom so an object of that class is
valid input for random.
Use this method to initiate a "key-based" key agreement with another party, the correspondent.
sharedParameters - A JSAFE_Parameters object containing
the system parameters.correspondentKey - The other party's key agreement public key.random - A SecureRandom object from which this object
draws random bytes if necessary.
JSAFE_InvalidParameterException - If the shared parameters
do not match the algorithm specified at instantiation.
JSAFE_InvalidKeyException - If the key does not match the
algorithm or shared parameters.
JSAFE_InvalidUseException - If the object does not possess a
random object.public abstract void keyAgreeInit(JSAFE_PublicKey correspondentKey, SecureRandom random) throws JSAFE_InvalidKeyException, JSAFE_InvalidParameterException, JSAFE_InvalidUseException
correspondentKey. If an algorithm needs random bytes, an
object gets them from random.
JSAFE_SecureRandom is a subclass of
java.security.SecureRandom, so an object of that class is
valid input for random.
This method expects the system parameters to be already loaded. Use this method to initiate a "key-based" key agreement with another party, the correspondent.
correspondentKey - The other party's key agreement public key.random - A SecureRandom object from which this object
draws random bytes if necessary.
JSAFE_InvalidParameterException - If the shared parameters
do not match the algorithm specified at instantiation.
JSAFE_InvalidKeyException - If the key does not match the
algorithm or shared parameters.
JSAFE_InvalidUseException - If the object does not possess
system parameters or a random object.public abstract void keyAgreeInit(JSAFE_Parameters sharedParameters, JSAFE_PrivateKey myKey, SecureRandom random) throws JSAFE_InvalidParameterException, JSAFE_InvalidKeyException, JSAFE_InvalidUseException
sharedParameters and myKey.
If an algorithm needs random bytes, the object gets them from
random. JSAFE_SecureRandom
is a subclass of java.security.SecureRandom, so an object of
that class is valid input for random.
If the private key does not contain the system parameters, this
method will use those found in sharedParameters. If the
private key does contain the system parameters, pass in null
for this argument.
Use this method to respond to a "key-based" key agreement.
sharedParameters - An object containing the system parameters.myKey - The caller's key agreement private key.random - A SecureRandom object from which this object
will draw random bytes if necessary.
JSAFE_InvalidParameterException - If the shared parameters
do not match the algorithm specified at instantiation.
JSAFE_InvalidKeyException - If the key does not match the
algorithm or shared parameters.
JSAFE_InvalidUseException - If the object does not possess a
random object.public abstract void keyAgreeInit(JSAFE_PrivateKey myKey, SecureRandom random) throws JSAFE_InvalidKeyException, JSAFE_InvalidParameterException, JSAFE_InvalidUseException
myKey. It computes key agreement values using
myKey and certain parameters. These parameters either reside
in the key object (if it was instantiated with parameters) or are already
loaded into the object. This method expects the system parameters to
already be loaded. This happens either at instantiation
(if the BER encoding of the algorithm identifier is used),
or by a previous call to keyAgreeInit().
If an algorithm needs random bytes, the object gets them from
random.
The JSAFE_SecureRandom object is a subclass of
java.security.SecureRandom, so an object of that class is
valid input for random.
Use this method to respond to a "key-based" key agreement.
myKey - The caller's key agreement private key.random - A SecureRandom object this object draws random
bytes from, if necessary.
JSAFE_InvalidParameterException - If the shared parameters
do not match the algorithm specified at instantiation.
JSAFE_InvalidKeyException - If the key does not match the
algorithm or shared parameters.
JSAFE_InvalidUseException - If the object does not possess
system parameters or a random object.
public abstract void keyAgreeReInit()
throws JSAFE_InvalidUseException
keyAgreeInit() method.
JSAFE_InvalidUseException - If the object has not yet been
initialized.
public byte[] keyAgreePhase1()
throws JSAFE_InvalidUseException
byte array.
Computes a private value and saves it in an object.
Call getPrivateValue() to retrieve the private value.
byte array containing the caller's public value.
JSAFE_InvalidUseException - If the object is not yet initialized.getPrivateValue()
public abstract int keyAgreePhase1(byte[] myPublicValue,
int offset)
throws JSAFE_InvalidUseException
myPublicValue,
beginning at offset. The return value is the length of the
public value, which is the number of bytes placed in the output buffer.
Computes a private value and saves it in an object.
Call getPrivateValue() to retrieve the private value.
myPublicValue - The buffer where the output is placed.offset - The offset into myPublicValue where the writing
begins.
JSAFE_InvalidUseException - If the object is not initialized.getPrivateValue()public abstract JSAFE_PublicKey generateMyPublicValue() throws JSAFE_InvalidUseException
JSAFE_PublicKey. This
is equivalent to Phase 1 when performing classical key
agreement. Before this method is called, the object must
have been initialized by a call to keyAgreeInit().
This method computes a private value and saves it in the
algorithm object. To retrieve this private value, call
getPrivateValue().
JSAFE_PublicKey object containing the public value
(and the system parameters).
JSAFE_InvalidUseException - If the object is not
initialized for key-based key agreement.
public byte[] keyAgreePhase2(byte[] correspondentPublicValue,
int offset,
int len)
throws JSAFE_InvalidUseException
keyAgreePhase1()
and the len bytes of correspondentPublicValue,
beginning at offset.
Returns the shared secret in a new byte array.
correspondentPublicValue - The other party's public value.offset - The offset into correspondentPublicValue where
the value begins.len - The length of the other party's public value.
byte array containing the shared secret.
JSAFE_InvalidUseException - If the object is not initialized.
public abstract int keyAgreePhase2(byte[] correspondentPublicValue,
int inOffset,
int len,
byte[] sharedSecret,
int outOffset)
throws JSAFE_InvalidUseException
sharedSecret, beginning at
outOffset. Uses the private value generated during
keyAgreePhase1() and the len
bytes of correspondentPublicValue, beginning at
inOffset.
The return value is the length of the shared secret, which is the number of
bytes placed in the output buffer.
Places the shared secret into the given byte array.
correspondentPublicValue - The other party's public value.inOffset - The offset into correspondentPublicValue where
the value actually begins.len - The length of the other party's public value.sharedSecret - The buffer where the computed shared secret is placed.outOffset - The offset into sharedSecret where the
writing begins.
JSAFE_InvalidUseException - If the object is not initialized.
public byte[] generateSharedSecret()
throws JSAFE_InvalidUseException
byte
array. This method uses the private value generated during
generateMyPublicValue() and the correspondent's public
value extracted from the public key passed in during
keyAgreeInit().
byte array containing the shared secret.
JSAFE_InvalidUseException - If the object is not initialized.
public abstract int generateSharedSecret(byte[] sharedSecret,
int offset)
throws JSAFE_InvalidUseException
byte array sharedSecret beginning at
offset.
The return value is the length of the shared secret, which is the
number of bytes placed in the output buffer. This method uses the
private value generated during generateMyPublicValue() and
the correspondent's public value extracted from the public key passed in
during keyAgreeInit(). This is equivalent to phase 2 when
performing classical key agreement.
This method should be called after generateMyPublicValue().
sharedSecret - The buffer where the computed shared secret is placed.offset - The offset into sharedSecret where the writing
begins.
JSAFE_InvalidUseException - If the object is not yet initialized.public byte[] generateSharedSecret(JSAFE_PublicKey correspondentKey) throws JSAFE_InvalidUseException, JSAFE_InvalidKeyException
byte
array. This method uses the private value extracted from
myKey during keyAgreeInit() and the
correspondent's public value extracted from correspondentKey.
This is equivalent to phase 2 when performing classical key agreement.
This method should be used when responding to another party's
initiation. Call this method after calling keyAgreeInit().
This method returns the shared secret in a new byte array.
correspondentKey - The other party's public value in the form of
a public key.
byte array containing the shared secret.
JSAFE_InvalidUseException - If the object is not initialized.
JSAFE_InvalidKeyException - If the key object does not match
the information loaded at initialization.public abstract int generateSharedSecret(JSAFE_PublicKey correspondentKey, byte[] sharedSecret, int offset) throws JSAFE_InvalidUseException, JSAFE_InvalidKeyException
sharedSecret, beginning at offset. This
method uses the private value extracted from myKey during
keyAgreeInit(), and the correspondent's public value that is
extracted from correspondentKey. The return value is the
length of the shared secret, which is the number of bytes placed in the
output buffer. This is equivalent to phase 2 when performing classical key
agreement. Use this method when responding to another party's
initiation. Call this method after calling keyAgreeInit().
correspondentKey - The other party's public value in the form of
a public key.sharedSecret - The buffer where the computed shared secret is placed.offset - The offset into sharedSecret where the writing
begins.
JSAFE_InvalidUseException - If the object is not initialized.
JSAFE_InvalidKeyException - If the key object does not match
the information loaded at initialization.
public byte[] getPrivateValue()
throws JSAFE_InvalidUseException
byte array. Returns the
private value computed in keyAgreePhase1 in a new
byte array.
byte array containing the private value.
JSAFE_InvalidUseException - If the private value is not generated.
public abstract int getPrivateValue(byte[] privateValue,
int offset)
throws JSAFE_InvalidUseException
privateValue
(beginning at offset) the private value that is computed in
keyAgreePhase1().
This method returns the length of the private value, which is the number
of bytes placed in the output buffer.
privateValue - The buffer where the generated private value is placed.offset - The offset into privateValue where the writing
begins.
JSAFE_InvalidUseException - If the private value is not generated.public abstract JSAFE_PrivateKey getPrivateValueAsKey() throws JSAFE_InvalidUseException
JSAFE_PrivateKey object that contains
the private value computed in generateMyPublicValue().
Retrieves the private value in the form of a private key.
JSAFE_PrivateKey object
(including the system parameters).
JSAFE_InvalidUseException - If the private value is not generated.public void clearSensitiveData()
clearSensitiveData(),
an Init (not a ReInit) method must
be called to perform other operations with the object.
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||