javax.crypto
Class KeyAgreement

java.lang.Object
  extended by javax.crypto.KeyAgreement

public class KeyAgreement
extends Object

Key agreement is a method in which two or more parties may agree on a secret key for symmetric cryptography or message authentication without transmitting any secrets in the clear. Key agreement algorithms typically use a public/private key pair, and the public key (along with some additional information) is sent across untrusted networks.

The most common form of key agreement used today is the Diffie-Hellman key exchange algorithm, described in PKCS #3 - Diffie Hellman Key Agreement Standard.

Since:
1.4
See Also:
KeyGenerator, SecretKey

Constructor Summary
protected KeyAgreement(KeyAgreementSpi kaSpi, Provider provider, String algorithm)
           
 
Method Summary
 Key doPhase(Key key, boolean lastPhase)
          Do a phase in the key agreement.
 byte[] generateSecret()
          Generate the shared secret in a new byte array.
 int generateSecret(byte[] sharedSecret, int offset)
          Generate the shared secret and store it into the supplied array.
 SecretKey generateSecret(String algorithm)
          Generate the shared secret and return it as an appropriate SecretKey.
 String getAlgorithm()
          Return the name of this key-agreement algorithm.
static KeyAgreement getInstance(String algorithm)
          Get an implementation of an algorithm from the first provider that implements it.
static KeyAgreement getInstance(String algorithm, Provider provider)
          Return an implementation of an algorithm from a specific provider.
static KeyAgreement getInstance(String algorithm, String provider)
          Return an implementation of an algorithm from a named provider.
 Provider getProvider()
          Return the provider of the underlying implementation.
 void init(Key key)
          Initialize this key agreement with a key.
 void init(Key key, AlgorithmParameterSpec params)
          Initialize this key agreement with a key and parameters.
 void init(Key key, AlgorithmParameterSpec params, SecureRandom random)
          Initialize this key agreement with a key, parameters, and source of randomness.
 void init(Key key, SecureRandom random)
          Initialize this key agreement with a key and a source of randomness.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

KeyAgreement

protected KeyAgreement(KeyAgreementSpi kaSpi,
                       Provider provider,
                       String algorithm)
Method Detail

getInstance

public static final KeyAgreement getInstance(String algorithm)
                                      throws NoSuchAlgorithmException
Get an implementation of an algorithm from the first provider that implements it.

Parameters:
algorithm - The name of the algorithm to get.
Returns:
The proper KeyAgreement instacne, if found.
Throws:
NoSuchAlgorithmException - If the specified algorithm is not implemented by any installed provider.
IllegalArgumentException - if algorithm is null or is an empty string.

getInstance

public static final KeyAgreement getInstance(String algorithm,
                                             String provider)
                                      throws NoSuchAlgorithmException,
                                             NoSuchProviderException
Return an implementation of an algorithm from a named provider.

Parameters:
algorithm - The name of the algorithm to create.
provider - The name of the provider from which to get the implementation.
Returns:
The proper KeyAgreement instance, if found.
Throws:
NoSuchAlgorithmException - If the named provider does not implement the algorithm.
NoSuchProviderException - If the named provider does not exist.
IllegalArgumentException - if either algorithm or provider is null, or if algorithm is an empty string.

getInstance

public static final KeyAgreement getInstance(String algorithm,
                                             Provider provider)
                                      throws NoSuchAlgorithmException
Return an implementation of an algorithm from a specific provider.

Parameters:
algorithm - The name of the algorithm to get.
provider - The provider from which to get the implementation.
Returns:
The proper KeyAgreement instance, if found.
Throws:
NoSuchAlgorithmException - If this provider does not implement the algorithm.
IllegalArgumentException - if either algorithm or provider is null, or if algorithm is an empty string.

doPhase

public final Key doPhase(Key key,
                         boolean lastPhase)
                  throws IllegalStateException,
                         InvalidKeyException
Do a phase in the key agreement. The number of times this method is called depends upon the algorithm and the number of parties involved, but must be called at least once with the lastPhase flag set to true.

Parameters:
key - The key for this phase.
lastPhase - Should be true if this will be the last phase before generating the shared secret.
Returns:
The intermediate result, or null if there is no intermediate result.
Throws:
IllegalStateException - If this instance has not been initialized.
InvalidKeyException - If the key is inappropriate for this algorithm.

generateSecret

public final byte[] generateSecret()
                            throws IllegalStateException
Generate the shared secret in a new byte array.

Returns:
The shared secret.
Throws:
IllegalStateException - If this instnace has not been initialized, or if not enough calls to doPhase have been made.

generateSecret

public final int generateSecret(byte[] sharedSecret,
                                int offset)
                         throws IllegalStateException,
                                ShortBufferException
Generate the shared secret and store it into the supplied array.

Parameters:
sharedSecret - The array in which to store the secret.
offset - The index in sharedSecret to start storing data.
Returns:
The length of the shared secret, in bytes.
Throws:
IllegalStateException - If this instnace has not been initialized, or if not enough calls to doPhase have been made.
ShortBufferException - If the supplied array is not large enough to store the result.

generateSecret

public final SecretKey generateSecret(String algorithm)
                               throws IllegalStateException,
                                      InvalidKeyException,
                                      NoSuchAlgorithmException
Generate the shared secret and return it as an appropriate SecretKey.

Parameters:
algorithm - The secret key's algorithm.
Returns:
The shared secret as a secret key.
Throws:
IllegalStateException - If this instnace has not been initialized, or if not enough calls to doPhase have been made.
InvalidKeyException - If the shared secret cannot be used to make a SecretKey.
NoSuchAlgorithmException - If the specified algorithm does not exist.

getAlgorithm

public final String getAlgorithm()
Return the name of this key-agreement algorithm.

Returns:
The algorithm name.

getProvider

public final Provider getProvider()
Return the provider of the underlying implementation.

Returns:
The provider.

init

public final void init(Key key)
                throws InvalidKeyException
Initialize this key agreement with a key. This method will use the highest-priority SecureRandom as its source of randomness.

Parameters:
key - The key, usually the user's private key.
Throws:
InvalidKeyException - If the supplied key is not appropriate.

init

public final void init(Key key,
                       SecureRandom random)
                throws InvalidKeyException
Initialize this key agreement with a key and a source of randomness.

Parameters:
key - The key, usually the user's private key.
random - The source of randomness.
Throws:
InvalidKeyException - If the supplied key is not appropriate.

init

public final void init(Key key,
                       AlgorithmParameterSpec params)
                throws InvalidAlgorithmParameterException,
                       InvalidKeyException
Initialize this key agreement with a key and parameters. This method will use the highest-priority SecureRandom as its source of randomness.

Parameters:
key - The key, usually the user's private key.
params - The algorithm parameters.
Throws:
InvalidAlgorithmParameterException - If the supplied parameters are not appropriate.
InvalidKeyException - If the supplied key is not appropriate.

init

public final void init(Key key,
                       AlgorithmParameterSpec params,
                       SecureRandom random)
                throws InvalidAlgorithmParameterException,
                       InvalidKeyException
Initialize this key agreement with a key, parameters, and source of randomness.

Parameters:
key - The key, usually the user's private key.
params - The algorithm parameters.
random - The source of randomness.
Throws:
InvalidAlgorithmParameterException - If the supplied parameters are not appropriate.
InvalidKeyException - If the supplied key is not appropriate.