javax.crypto
Class KeyAgreement

java.lang.Object
  |
  +--javax.crypto.KeyAgreement

public class KeyAgreement

extends Object

Engine class for algorithm independent Key Agreement.

Attention: This is not a SUN implementation!

This class has been developed by IAIK according to the documentation publically available.
For SUN´s documentation of this class see http://java.sun.com/security/JCE1.2/spec/apidoc/index.html

This class provides the functionality of a key agreement algorithm. A key agreement algorithm (e.g. Diffie Hellman) is used for creating some shared secret between the involved parties by performing several phases, predicted by the specified algorithm.

A KeyAgreement object is created using a proper getInstance() factory method. After initializing the KeyAgreement object, each requested phase is performed by the doPhase method thereby using an extra flag for explicitly specifying if the actually executed phase already is the last phase of this key agreement. Finally, each involved party creates the shared secret by calling a generateSecret method.

After the shared secret finally has been created, the KeyAgreement object is reset for being able to be used for further key agreements, either by using the same private key information as specified at the beginning of the key agreement, or using new parameters by properly initializing this KeyAgreement object again.

Version:

File Revision 15

Constructor Summary

protected

KeyAgreement(KeyAgreementSpi keyAgreeSpi, Provider provider, String algorithm) Creates a KeyAgreement object.

Method Summary

Key	doPhase(Key key, boolean lastPhase) Returns the key resulting from the next phase of this key agreement.
byte[]	generateSecret() Returns the shared secret finally generated by this key agreement algorithm.
int	generateSecret(byte[] sharedSecret, int offset) Generates the shared secret finishing this key agreement procedure and writes it into the given byte array, beginning at the given offset position.
SecretKey	generateSecret(String algorithm) Returns the shared secret finally generated by this key agreement algorithm as SecretKey to be used for the secret key algorithm given by its name.
String	getAlgorithm() Returns the standard name of the key agreement algorithm.
static KeyAgreement	getInstance(String algorithm) Returns the default provider KeyAgreement implementation for the specified key agreement algorithm.
static KeyAgreement	getInstance(String algorithm, String provider) Returns a KeyAgreement object for the specified key agreement algorithm, implemented by the given provider.
Provider	getProvider() Returns the provider used for creating this KeyAgreement object.
void	init(Key key) Initializes this KeyAgreement with the given key, which constitutes the private key (including all required algorithm parameters) of some entity being involved in this key agreement procedure.
void	init(Key key, AlgorithmParameterSpec params) Initializes this KeyAgreement with the given key and algorithm parameters, where the given key constitutes the private key of some entity being involved in this key agreement procedure.
void	init(Key key, AlgorithmParameterSpec params, SecureRandom random) Initializes this KeyAgreement with the given key, algorithm parameters, and random seed.
void	init(Key key, SecureRandom random) Initializes this KeyAgreement with the given key and random seed, where the given key constitutes the private key (including all required algorithm parameters) of some entity being involved in this key agreement procedure.

Methods inherited from class java.lang.Object

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

Constructor Detail

KeyAgreement

protected KeyAgreement(KeyAgreementSpi keyAgreeSpi,
                       Provider provider,
                       String algorithm)

Creates a KeyAgreement object. Only internally used for creating a KeyAgreement object. Applications shall use one of the getInstance factory methods for obtaining a KeyAgreemant object.

Parameters:

keyAgreeSpi - the SPI KeyAgreement implementation of the actual provider

provider - the provider

algorithm - the algorithm

Method Detail

getAlgorithm

public final String getAlgorithm()

Returns the standard name of the key agreement algorithm.

Returns:

the standard name od the algorithm as string

getInstance

public static final KeyAgreement getInstance(String algorithm)
                                      throws NoSuchAlgorithmException

Returns the default provider KeyAgreement implementation for the specified key agreement algorithm.

Parameters:

algorithm - the standard name of the key agreement algorithm

Returns:

the new KeyAgreement object

Throws:

NoSuchAlgorithmException - if this algorithm is not implemented

getInstance

public static final KeyAgreement getInstance(String algorithm,
                                             String provider)
                                      throws NoSuchAlgorithmException,
                                             NoSuchProviderException

Returns a KeyAgreement object for the specified key agreement algorithm, implemented by the given provider.

Parameters:

algorithm - the standard name of the key agreement algorithm

provider - the name of the provider as String

Returns:

the new KeyAgreement object

Throws:

NoSuchAlgorithmException - if this algorithm is not implemented

NoSuchProviderException - if the given provider cannot be fetched

getProvider

public final Provider getProvider()

Returns the provider used for creating this KeyAgreement object.

Returns:

the provider used for creating this KeyAgreement object

init

public final void init(Key key)
                throws InvalidKeyException

Initializes this KeyAgreement with the given key, which constitutes the private key (including all required algorithm parameters) of some entity being involved in this key agreement procedure. Each entity being involved in a key agreement process has to create a KeyAgreement object and subsequently initialize it with the entity´s private key for bringing in the private information which will be accessed when required during any phase of the key agreement process. Any key material later supplied to any of the doFinal methods will represent public key material of another participated entity or key material resulting from some previously performed phase (if there are more than two entities involved in the key agreement).

Parameters:

key - the private key information of the entity involved in the key agreement

Throws:

InvalidKeyException - if the given key cannot be used for this key agreement

init

public final void init(Key key,
                       SecureRandom random)
                throws InvalidKeyException

Initializes this KeyAgreement with the given key and random seed, where the given key constitutes the private key (including all required algorithm parameters) of some entity being involved in this key agreement procedure. Each entity being involved in a key agreement process has to create a KeyAgreement object and subsequently initialize it with the entity´s private key for bringing in the private information which will be accessed when required during any phase of the key agreement process. Any key material later supplied to any of the doFinal methods will represent public key material of another participated entity or key material resulting from some previously performed phase (if there are more than two entities involved in the key agreement).

Parameters:

key - the private key information of the entity involved in the key agreement

random - the random seed

Throws:

InvalidKeyException - if the given key cannot be used for this key agreement

init

public final void init(Key key,
                       AlgorithmParameterSpec params)
                throws InvalidKeyException,
                       InvalidAlgorithmParameterException

Initializes this KeyAgreement with the given key and algorithm parameters, where the given key constitutes the private key of some entity being involved in this key agreement procedure. Each entity being involved in a key agreement process has to create a KeyAgreement object and subsequently initialize it with the entity´s private key for bringing in the private information which will be accessed when required during any phase of the key agreement process. Any key material later supplied to any of the doFinal methods will represent public key material of another participated entity or key material resulting from some previously performed phase (if there are more than two entities involved in the key agreement).

Parameters:

key - the private key information of the entity involved in the key agreement

params - the algorithm parameters used for this key agreement algorithm

Throws:

InvalidKeyException - if the given key cannot be used for this key agreement

InvalidAlgorithmParameterException - if the given parameters do not match to this key agreement algorithm

init

public final void init(Key key,
                       AlgorithmParameterSpec params,
                       SecureRandom random)
                throws InvalidKeyException,
                       InvalidAlgorithmParameterException

Initializes this KeyAgreement with the given key, algorithm parameters, and random seed. The given key constitutes the private key of some entity being involved in this key agreement procedure. Each entity being involved in a key agreement process has to create a KeyAgreement object and subsequently initialize it with the entity´s private key for bringing in the private information which will be accessed when required during any phase of the key agreement process. Any key material later supplied to any of the doFinal methods will represent public key material of another participated entity or key material resulting from some previously performed phase (if there are more than two entities involved in the key agreement).

Parameters:

key - the private key information of the entity involved in the key agreement

params - the algorithm parameters used for this key agreement algorithm

random - the random seed

Throws:

InvalidKeyException - if the given key cannot be used for this key agreement

InvalidAlgorithmParameterException - if the given parameters do not match to this key agreement algorithm

doPhase

public final Key doPhase(Key key,
                         boolean lastPhase)
                  throws IllegalStateException,
                         InvalidKeyException

Returns the key resulting from the next phase of this key agreement.

Parameters:

key - the required key for this phase, supplied by some other entity involved in this key agreement

lastPhase - true if this is the last phase of this key agreemant, false if not

Returns:

the key resulting from this phase, or null if no key is returned by this phase

Throws:

InvalidKeyException - if the given key cannot be used for this key agreement algorithm / phase

IllegalStateException - if the given phase cannot be performed in this state of the key agreement procedure

generateSecret

public final byte[] generateSecret()
                            throws IllegalStateException

Returns the shared secret finally generated by this key agreement algorithm. After creating the shared secret, this KeyAgreement object is reset for being able to be used for further key agreements, either by using the same private key information as specified at the beginning of the key agreement, or using new parameters by properly initializing this KeyAgreement object again.

Returns:

the generated shared secret within a byte array

Throws:

IllegalStateException - if this key agreement procedure yet is not ready for being finished by generating the shared secret

generateSecret

public final int generateSecret(byte[] sharedSecret,
                                int offset)
                         throws IllegalStateException,
                                ShortBufferException

Generates the shared secret finishing this key agreement procedure and writes it into the given byte array, beginning at the given offset position. After creating the shared secret, this KeyAgreement object is reset for being able to be used for further key agreements, either by using the same private key information as specified at the beginning of the key agreement, or using new parameters by properly initializing this KeyAgreement object again.

Parameters:

sharedSecret - the byte array to which the generated secret has to be written

offset - the offset indicating the start position within the output byte array to which to write the generated shared secret

Returns:

number of bytes that are stored in the output byte array

Throws:

IllegalStateException - if this key agreement procedure yet is not ready for being finished by generating the shared secret

ShortBufferException - if the given output buffer is too small for holding the generated secret

generateSecret

public final SecretKey generateSecret(String algorithm)
                               throws IllegalStateException,
                                      NoSuchAlgorithmException,
                                      InvalidKeyException

Returns the shared secret finally generated by this key agreement algorithm as SecretKey to be used for the secret key algorithm given by its name. After creating the shared secret, this KeyAgreement object is reset for being able to be used for further key agreements, either by using the same private key information as specified at the beginning of the key agreement, or using new parameters by properly initializing this KeyAgreement object again.

Parameters:

algorithm - the name of the secret key algorithm for which the generated secret key shall be used

Returns:

the generated shared secret as SecretKey

Throws:

IllegalStateException - if this key agreement procedure yet is not ready for being finished by generating the shared secret

NoSuchAlgorithmException - if the given secret key algorithm is not supported

InvalidKeyException - if the generated shared secret cannot be returned as SecretKey matching to the given algorithm