javax.crypto
Class KeyAgreementSpi

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

Direct Known Subclasses:

DHKeyAgreement, ESDHKeyAgreement

public abstract class KeyAgreementSpi

extends Object

Service Provider Interface (SPI) for the KeyAgreement class.

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 SPI class has to be implemented by a particular provider for every key agreement algorithm to be supported.

The corresponding API class actually used by an application for key agreement is the javax.crypto.KeyAgreement class.

A KeyAgreement object is created using a proper KeyAgreement.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 13

See Also:

KeyAgreement

Constructor Summary

KeyAgreementSpi()
Default Constructor.

Method Summary

protected abstract Key	engineDoPhase(Key key, boolean lastPhase) Returns the key resulting from the next phase of this key agreement.
protected abstract byte[]	engineGenerateSecret() Returns the shared secret finally generated by this key agreement.
protected abstract int	engineGenerateSecret(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.
protected abstract SecretKey	engineGenerateSecret(String algorithm) Returns the shared secret finally generated by this key agreement as SecretKey to be used for the secret key algorithm given by its name.
protected abstract void	engineInit(Key key, AlgorithmParameterSpec params, SecureRandom random) Initializes this KeyAgreement with the given key, algorithm parameters, and random seed.
protected abstract void	engineInit(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

KeyAgreementSpi

public KeyAgreementSpi()

Default Constructor.

Method Detail

engineInit

protected abstract void engineInit(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

engineInit

protected abstract void engineInit(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

engineDoPhase

protected abstract Key engineDoPhase(Key key,
                                     boolean lastPhase)
                              throws InvalidKeyException,
                                     IllegalStateException

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

engineGenerateSecret

protected abstract byte[] engineGenerateSecret()
                                        throws IllegalStateException

Returns the shared secret finally generated by this key agreement. 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

engineGenerateSecret

protected abstract int engineGenerateSecret(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:

the 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 secret

engineGenerateSecret

protected abstract SecretKey engineGenerateSecret(String algorithm)
                                           throws IllegalStateException,
                                                  NoSuchAlgorithmException,
                                                  InvalidKeyException

Returns the shared secret finally generated by this key agreement 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