javax.crypto

Class 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

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 {@link 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, String provider) Return an implementation of an algorithm from a named provider.
static KeyAgreement	getInstance(String algorithm, Provider provider) Return an implementation of an algorithm from a specific 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, SecureRandom random) Initialize this key agreement with a key and a source of randomness.
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.

Constructor Detail

KeyAgreement

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

Method Detail

doPhase

public final Key doPhase(Key key, boolean lastPhase)

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: java.lang.IllegalStateException If this instance has not been initialized. java.security.InvalidKeyException If the key is inappropriate for this algorithm.

generateSecret

public final byte[] generateSecret()

Generate the shared secret in a new byte array.

Returns: The shared secret.

Throws: java.lang.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)

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: java.lang.IllegalStateException If this instnace has not been initialized, or if not enough calls to doPhase have been made. javax.crypto.ShortBufferException If the supplied array is not large enough to store the result.

generateSecret

public final SecretKey generateSecret(String algorithm)

Generate the shared secret and return it as an appropriate {@link SecretKey}.

Parameters: algorithm The secret key's algorithm.

Returns: The shared secret as a secret key.

Throws: java.lang.IllegalStateException If this instnace has not been initialized, or if not enough calls to doPhase have been made. java.security.InvalidKeyException If the shared secret cannot be used to make a {@link SecretKey}. java.security.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.

getInstance

public static final KeyAgreement getInstance(String algorithm)

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)

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)

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.

getProvider

public final Provider getProvider()

Return the provider of the underlying implementation.

Returns: The provider.

init

public final void init(Key key)

Initialize this key agreement with a key. This method will use the highest-priority {@link java.security.SecureRandom} as its source of randomness.

Parameters: key The key, usually the user's private key.

Throws: java.security.InvalidKeyException If the supplied key is not appropriate.

init

public final void init(Key key, SecureRandom random)

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: java.security.InvalidKeyException If the supplied key is not appropriate.

init

public final void init(Key key, AlgorithmParameterSpec params)

Initialize this key agreement with a key and parameters. This method will use the highest-priority {@link java.security.SecureRandom} as its source of randomness.

Parameters: key The key, usually the user's private key. params The algorithm parameters.

Throws: java.security.InvalidAlgorithmParameterException If the supplied parameters are not appropriate. java.security.InvalidKeyException If the supplied key is not appropriate.

init

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

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: java.security.InvalidAlgorithmParameterException If the supplied parameters are not appropriate. java.security.InvalidKeyException If the supplied key is not appropriate.