javax.crypto

Class KeyAgreement

java.lang.Object

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

Constructors

Modifier	Constructor and Description
protected	KeyAgreement(KeyAgreementSpi kaSpi, Provider provider, String algorithm)

Method Summary

Methods

Modifier and Type	Method and Description
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.