APIdia Launch Partner
Top Description Fields Constructors Methods
javax.crypto

public Class KeyAgreement

extends Object
Class Inheritance
Imports
java.util.*, java.security.*, .Provider.Service, java.security.spec.*, sun.security.util.Debug, sun.security.jca.*, .GetInstance.Instance
This class provides the functionality of a key agreement (or key exchange) protocol.

The keys involved in establishing a shared secret are created by one of the key generators (KeyPairGenerator or KeyGenerator), a KeyFactory, or as a result from an intermediate phase of the key agreement protocol.

For each of the correspondents in the key exchange, doPhase needs to be called. For example, if this key exchange is with one other party, doPhase needs to be called once, with the lastPhase flag set to true. If this key exchange is with two other parties, doPhase needs to be called twice, the first time setting the lastPhase flag to false, and the second time setting it to true. There may be any number of parties involved in a key exchange. However, support for key exchanges with more than two parties is implementation specific or as specified by the standard key agreement algorithm.

Every implementation of the Java platform is required to support the following standard KeyAgreement algorithms. For the "ECDH" algorithm, implementations must support the curves in parentheses.

These algorithms are described in the KeyAgreement section of the Java Security Standard Algorithm Names Specification. Consult the release documentation for your implementation to see if any other algorithms are supported.
Author
Jan Luehe
Since
1.4
External Specification
Java Security Standard Algorithm Names
See Also
KeyGenerator, SecretKey

Field Summary

Modifier and TypeField and Description
private final String
algorithm

private static final Debug
debug

private Provider.Service
firstService

private static final int
I_NO_PARAMS

private static final int
I_PARAMS

private final Object
lock

private static final Debug
pdebug

private Provider
provider

private Iterator<Provider.Service>
serviceIterator

private static final boolean
skipDebug

private KeyAgreementSpi
spi

private static int
warnCount

Constructor Summary

AccessConstructor and Description
protected
KeyAgreement(KeyAgreementSpi
the delegate
keyAgreeSpi, Provider
the provider
provider, String
the algorithm
algorithm)

Creates a KeyAgreement object.

private
KeyAgreement(Provider.Service s, Iterator<Provider.Service> t, String algorithm)

Method Summary

Modifier and TypeMethod and Description
pack-priv void
chooseFirstProvider()

Choose the Spi from the first provider available.

private void
chooseProvider(int initType, Key key, AlgorithmParameterSpec params, SecureRandom random)

public final Key

Returns:

the (intermediate) key resulting from this phase, or null if this phase does not yield a key
doPhase(Key
the key for this phase. For example, in the case of Diffie-Hellman between 2 parties, this would be the other party's Diffie-Hellman public key.
key, boolean
flag which indicates whether this is the last phase of this key agreement.
lastPhase)

Executes the next phase of this key agreement with the given key that was received from one of the other parties involved in this key agreement.

public final byte[]

Returns:

the new buffer with the shared secret
generateSecret()

Generates the shared secret and returns it in a new buffer.

public final int

Returns:

the number of bytes placed into sharedSecret
generateSecret(byte[]
the buffer for the shared secret
sharedSecret, int
the offset in sharedSecret where the shared secret will be stored
offset)

Generates the shared secret, and places it into the buffer sharedSecret, beginning at offset inclusive.

public final SecretKey

Returns:

the shared secret key. The length of the key material may be adjusted to be compatible with the specified algorithm, regardless of whether the key is extractable. If algorithm is specified as "Generic" and it is supported by the implementation, the full shared secret is returned.
generateSecret(String
the requested secret key algorithm. This is different from the KeyAgreement algorithm provided to the getInstance method. See the SecretKey Algorithms section in the Java Security Standard Algorithm Names Specification for information about standard secret key algorithm names. Specify "Generic" if the output will be used as the input keying material of a key derivation function (KDF).
algorithm)

Creates the shared secret and returns it as a SecretKey object of the specified algorithm.

public final String

Returns:

the algorithm name of this KeyAgreement object.
getAlgorithm()

Returns the algorithm name of this KeyAgreement object.

public static final KeyAgreement

Returns:

the new KeyAgreement object
getInstance(String
the standard name of the requested key agreement algorithm. See the KeyAgreement section in the Java Security Standard Algorithm Names Specification for information about standard algorithm names.
algorithm)

Returns a KeyAgreement object that implements the specified key agreement algorithm.

public static final KeyAgreement

Returns:

the new KeyAgreement object
getInstance(String
the standard name of the requested key agreement algorithm. See the KeyAgreement section in the Java Security Standard Algorithm Names Specification for information about standard algorithm names.
algorithm, String
the name of the provider.
provider)

Returns a KeyAgreement object that implements the specified key agreement algorithm.

public static final KeyAgreement

Returns:

the new KeyAgreement object
getInstance(String
the standard name of the requested key agreement algorithm. See the KeyAgreement section in the Java Security Standard Algorithm Names Specification for information about standard algorithm names.
algorithm, Provider
the provider.
provider)

Returns a KeyAgreement object that implements the specified key agreement algorithm.

public final Provider

Returns:

the provider of this KeyAgreement object
getProvider()

Returns the provider of this KeyAgreement object.

private String
getProviderName()

private void
implInit(KeyAgreementSpi spi, int type, Key key, AlgorithmParameterSpec params, SecureRandom random)

public final void
init(Key
the party's private information. For example, in the case of the Diffie-Hellman key agreement, this would be the party's own Diffie-Hellman private key.
key)

Initializes this key agreement with the given key, which is required to contain all the algorithm parameters required for this key agreement.

public final void
init(Key
the party's private information. For example, in the case of the Diffie-Hellman key agreement, this would be the party's own Diffie-Hellman private key.
key, SecureRandom
the source of randomness
random)

Initializes this key agreement with the given key and source of randomness.

public final void
init(Key
the party's private information. For example, in the case of the Diffie-Hellman key agreement, this would be the party's own Diffie-Hellman private key.
key, AlgorithmParameterSpec
the key agreement parameters
params)

Initializes this key agreement with the given key and set of algorithm parameters.

public final void
init(Key
the party's private information. For example, in the case of the Diffie-Hellman key agreement, this would be the party's own Diffie-Hellman private key.
key, AlgorithmParameterSpec
the key agreement parameters
params, SecureRandom
the source of randomness
random)

Initializes this key agreement with the given key, set of algorithm parameters, and source of randomness.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

algorithmback to summary
private final String algorithm
debugback to summary
private static final Debug debug
firstServiceback to summary
private Provider.Service firstService
I_NO_PARAMSback to summary
private static final int I_NO_PARAMS
I_PARAMSback to summary
private static final int I_PARAMS
lockback to summary
private final Object lock
pdebugback to summary
private static final Debug pdebug
providerback to summary
private Provider provider
serviceIteratorback to summary
private Iterator<Provider.Service> serviceIterator
skipDebugback to summary
private static final boolean skipDebug
spiback to summary
private KeyAgreementSpi spi
warnCountback to summary
private static int warnCount

Constructor Detail

KeyAgreementback to summary
protected KeyAgreement(KeyAgreementSpi keyAgreeSpi, Provider provider, String algorithm)

Creates a KeyAgreement object.

Parameters
keyAgreeSpi:KeyAgreementSpi

the delegate

provider:Provider

the provider

algorithm:String

the algorithm

KeyAgreementback to summary
private KeyAgreement(Provider.Service s, Iterator<Provider.Service> t, String algorithm)

Method Detail

chooseFirstProviderback to summary
pack-priv void chooseFirstProvider()

Choose the Spi from the first provider available. Used if delayed provider selection is not possible because init() is not the first method called.

chooseProviderback to summary
private void chooseProvider(int initType, Key key, AlgorithmParameterSpec params, SecureRandom random) throws InvalidKeyException, InvalidAlgorithmParameterException
doPhaseback to summary
public final Key doPhase(Key key, boolean lastPhase) throws InvalidKeyException, IllegalStateException

Executes the next phase of this key agreement with the given key that was received from one of the other parties involved in this key agreement.

Parameters
key:Key

the key for this phase. For example, in the case of Diffie-Hellman between 2 parties, this would be the other party's Diffie-Hellman public key.

lastPhase:boolean

flag which indicates whether this is the last phase of this key agreement.

Returns:Key

the (intermediate) key resulting from this phase, or null if this phase does not yield a key

Exceptions
InvalidKeyException:
if the given key is inappropriate for this phase.
IllegalStateException:
if this key agreement has not been initialized.
generateSecretback to summary
public final byte[] generateSecret() throws IllegalStateException

Generates the shared secret and returns it in a new buffer.

This method resets this KeyAgreement object to the state that it was in after the most recent call to one of the init methods. After a call to generateSecret, the object can be reused for further key agreement operations by calling doPhase to supply new keys, and then calling generateSecret to produce a new secret. In this case, the private information and algorithm parameters supplied to init will be used for multiple key agreement operations. The init method can be called after generateSecret to change the private information used in subsequent operations.

Returns:byte[]

the new buffer with the shared secret

Exceptions
IllegalStateException:
if this key agreement has not been initialized or if doPhase has not been called to supply the keys for all parties in the agreement
generateSecretback to summary
public final int generateSecret(byte[] sharedSecret, int offset) throws IllegalStateException, ShortBufferException

Generates the shared secret, and places it into the buffer sharedSecret, beginning at offset inclusive.

If the sharedSecret buffer is too small to hold the result, a ShortBufferException is thrown. In this case, this call should be repeated with a larger output buffer.

This method resets this KeyAgreement object to the state that it was in after the most recent call to one of the init methods. After a call to generateSecret, the object can be reused for further key agreement operations by calling doPhase to supply new keys, and then calling generateSecret to produce a new secret. In this case, the private information and algorithm parameters supplied to init will be used for multiple key agreement operations. The init method can be called after generateSecret to change the private information used in subsequent operations.

Parameters
sharedSecret:byte[]

the buffer for the shared secret

offset:int

the offset in sharedSecret where the shared secret will be stored

Returns:int

the number of bytes placed into sharedSecret

Exceptions
IllegalStateException:
if this key agreement has not been initialized or if doPhase has not been called to supply the keys for all parties in the agreement
ShortBufferException:
if the given output buffer is too small to hold the secret
generateSecretback to summary
public final SecretKey generateSecret(String algorithm) throws IllegalStateException, NoSuchAlgorithmException, InvalidKeyException

Creates the shared secret and returns it as a SecretKey object of the specified algorithm.

This method resets this KeyAgreement object to the state that it was in after the most recent call to one of the init methods. After a call to generateSecret, the object can be reused for further key agreement operations by calling doPhase to supply new keys, and then calling generateSecret to produce a new secret. In this case, the private information and algorithm parameters supplied to init will be used for multiple key agreement operations. The init method can be called after generateSecret to change the private information used in subsequent operations.

Parameters
algorithm:String

the requested secret key algorithm. This is different from the KeyAgreement algorithm provided to the getInstance method. See the SecretKey Algorithms section in the Java Security Standard Algorithm Names Specification for information about standard secret key algorithm names. Specify "Generic" if the output will be used as the input keying material of a key derivation function (KDF).

Returns:SecretKey

the shared secret key. The length of the key material may be adjusted to be compatible with the specified algorithm, regardless of whether the key is extractable. If algorithm is specified as "Generic" and it is supported by the implementation, the full shared secret is returned.

Exceptions
IllegalStateException:
if this key agreement has not been initialized or if doPhase has not been called to supply the keys for all parties in the agreement
NoSuchAlgorithmException:
if the specified secret key algorithm is not supported
InvalidKeyException:
if the shared secret key material cannot be used to generate a secret key of the specified algorithm (e.g., the key material is too short)
External Specification
Java Security Standard Algorithm Names
getAlgorithmback to summary
public final String getAlgorithm()

Returns the algorithm name of this KeyAgreement object.

This is the same name that was specified in one of the getInstance calls that created this KeyAgreement object.

Returns:String

the algorithm name of this KeyAgreement object.

getInstanceback to summary
public static final KeyAgreement getInstance(String algorithm) throws NoSuchAlgorithmException

Returns a KeyAgreement object that implements the specified key agreement algorithm.

This method traverses the list of registered security providers, starting with the most preferred provider. A new KeyAgreement object encapsulating the KeyAgreementSpi implementation from the first provider that supports the specified algorithm is returned.

Note that the list of registered providers may be retrieved via the Security.getProviders() method.

Implementation Note

The JDK Reference Implementation additionally uses the jdk.security.provider.preferred Security property to determine the preferred provider order for the specified algorithm. This may be different from the order of providers returned by Security.getProviders().

Parameters
algorithm:String

the standard name of the requested key agreement algorithm. See the KeyAgreement section in the Java Security Standard Algorithm Names Specification for information about standard algorithm names.

Returns:KeyAgreement

the new KeyAgreement object

Exceptions
NoSuchAlgorithmException:
if no Provider supports a KeyAgreementSpi implementation for the specified algorithm
NullPointerException:
if algorithm is null
External Specification
Java Security Standard Algorithm Names
See Also
java.security.Provider
getInstanceback to summary
public static final KeyAgreement getInstance(String algorithm, String provider) throws NoSuchAlgorithmException, NoSuchProviderException

Returns a KeyAgreement object that implements the specified key agreement algorithm.

A new KeyAgreement object encapsulating the KeyAgreementSpi implementation from the specified provider is returned. The specified provider must be registered in the security provider list.

Note that the list of registered providers may be retrieved via the Security.getProviders() method.

Parameters
algorithm:String

the standard name of the requested key agreement algorithm. See the KeyAgreement section in the Java Security Standard Algorithm Names Specification for information about standard algorithm names.

provider:String

the name of the provider.

Returns:KeyAgreement

the new KeyAgreement object

Exceptions
NoSuchAlgorithmException:
if a KeyAgreementSpi implementation for the specified algorithm is not available from the specified provider
NoSuchProviderException:
if the specified provider is not registered in the security provider list
IllegalArgumentException:
if the provider is null or empty
NullPointerException:
if algorithm is null
External Specification
Java Security Standard Algorithm Names
See Also
java.security.Provider
getInstanceback to summary
public static final KeyAgreement getInstance(String algorithm, Provider provider) throws NoSuchAlgorithmException

Returns a KeyAgreement object that implements the specified key agreement algorithm.

A new KeyAgreement object encapsulating the KeyAgreementSpi implementation from the specified provider is returned. Note that the specified provider does not have to be registered in the provider list.

Parameters
algorithm:String

the standard name of the requested key agreement algorithm. See the KeyAgreement section in the Java Security Standard Algorithm Names Specification for information about standard algorithm names.

provider:Provider

the provider.

Returns:KeyAgreement

the new KeyAgreement object

Exceptions
NoSuchAlgorithmException:
if a KeyAgreementSpi implementation for the specified algorithm is not available from the specified Provider object
IllegalArgumentException:
if the provider is null
NullPointerException:
if algorithm is null
External Specification
Java Security Standard Algorithm Names
See Also
java.security.Provider
getProviderback to summary
public final Provider getProvider()

Returns the provider of this KeyAgreement object.

Returns:Provider

the provider of this KeyAgreement object

getProviderNameback to summary
private String getProviderName()
implInitback to summary
private void implInit(KeyAgreementSpi spi, int type, Key key, AlgorithmParameterSpec params, SecureRandom random) throws InvalidKeyException, InvalidAlgorithmParameterException
initback to summary
public final void init(Key key) throws InvalidKeyException

Initializes this key agreement with the given key, which is required to contain all the algorithm parameters required for this key agreement.

If this key agreement requires any random bytes, it will get them using the java.security.SecureRandom implementation of the highest-priority installed provider as the source of randomness. (If none of the installed providers supply an implementation of SecureRandom, a system-provided source of randomness will be used.)

Parameters
key:Key

the party's private information. For example, in the case of the Diffie-Hellman key agreement, this would be the party's own Diffie-Hellman private key.

Exceptions
InvalidKeyException:
if the given key is inappropriate for this key agreement, e.g., is of the wrong type or has an incompatible algorithm type.
initback to summary
public final void init(Key key, SecureRandom random) throws InvalidKeyException

Initializes this key agreement with the given key and source of randomness. The given key is required to contain all the algorithm parameters required for this key agreement.

If the key agreement algorithm requires random bytes, it gets them from the given source of randomness, random. However, if the underlying algorithm implementation does not require any random bytes, random is ignored.

Parameters
key:Key

the party's private information. For example, in the case of the Diffie-Hellman key agreement, this would be the party's own Diffie-Hellman private key.

random:SecureRandom

the source of randomness

Exceptions
InvalidKeyException:
if the given key is inappropriate for this key agreement, e.g., is of the wrong type or has an incompatible algorithm type.
initback to summary
public final void init(Key key, AlgorithmParameterSpec params) throws InvalidKeyException, InvalidAlgorithmParameterException

Initializes this key agreement with the given key and set of algorithm parameters.

If this key agreement requires any random bytes, it will get them using the java.security.SecureRandom implementation of the highest-priority installed provider as the source of randomness. (If none of the installed providers supply an implementation of SecureRandom, a system-provided source of randomness will be used.)

Parameters
key:Key

the party's private information. For example, in the case of the Diffie-Hellman key agreement, this would be the party's own Diffie-Hellman private key.

params:AlgorithmParameterSpec

the key agreement parameters

Exceptions
InvalidKeyException:
if the given key is inappropriate for this key agreement, e.g., is of the wrong type or has an incompatible algorithm type.
InvalidAlgorithmParameterException:
if the given parameters are inappropriate for this key agreement.
initback to summary
public final void init(Key key, AlgorithmParameterSpec params, SecureRandom random) throws InvalidKeyException, InvalidAlgorithmParameterException

Initializes this key agreement with the given key, set of algorithm parameters, and source of randomness.

Parameters
key:Key

the party's private information. For example, in the case of the Diffie-Hellman key agreement, this would be the party's own Diffie-Hellman private key.

params:AlgorithmParameterSpec

the key agreement parameters

random:SecureRandom

the source of randomness

Exceptions
InvalidKeyException:
if the given key is inappropriate for this key agreement, e.g., is of the wrong type or has an incompatible algorithm type.
InvalidAlgorithmParameterException:
if the given parameters are inappropriate for this key agreement.