h49450 s 00038/00201/00292 d D 1.6 97/12/09 15:24:46 luehe 7 6 c rm ,* e s 00004/00004/00489 d D 1.5 97/11/18 08:49:06 luehe 6 5 c replaced "Architecture" with "Extension" when referring to API Spec & Reference Guide e s 00004/00004/00489 d D 1.4 97/11/17 13:31:22 luehe 5 4 c removed "#ApplA" from anchor reference e s 00003/00049/00490 d D 1.3 97/10/18 14:18:37 luehe 4 3 c moved javadocs example to JCESpec document (just to be safe ...) e s 00002/00003/00537 d D 1.2 97/10/10 12:42:06 luehe 3 1 c fixed getProvider javadocs e s 00000/00000/00000 d R 1.2 97/10/09 09:58:15 Codemgr 2 1 c SunPro Code Manager data about conflicts, renames, etc... c Name history : 1 0 security/JCE1.2/earlyaccess/javax.crypto.KeyAgreement.html e s 00540/00000/00000 d D 1.1 97/10/09 09:58:14 luehe 1 0 c date and time created 97/10/09 09:58:14 by luehe e u U f e 0 t T I 1 D 3 E 3 I 3 D 4 E 4 I 4 D 7 E 7 I 7 E 7 E 4 E 3 Class javax.crypto.KeyAgreement
D 4
All Packages  Class Hierarchy  This Package  Previous  Next  Index
E 4 I 4 D 7 All Packages Class Hierarchy This Package Previous Next Index E 7 I 7 All Packages Class Hierarchy This Package Previous Next Index E 7 E 4

Class javax.crypto.KeyAgreement

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

D 7
public abstract class KeyAgreement E 7 I 7
public class KeyAgreement E 7
extends Object
This class provides the functionality of a key agreement 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 (see doPhase). D 4

The following sequence of calls illustrates a Diffie-Hellman key agreement between two parties, Alice and Bob, including the generation of Diffie-Hellman parameters by Alice. In Phase 1 of the Diffie-Hellman protocol, Alice and Bob use the Diffie-Hellman parameters generated by Alice to produce a public value and a private value. In Phase 2, they trade public values and each uses the other's public value with their own private value to generate the same secret value. This example describes the key agreement protocol from Alice's perspective.

 import java.security.*;
 import java.security.spec.*;
 

// ALICE: creates her own Diffie-Hellman key pair; she chooses a prime // modulus size of 1024 bits. As part of the key pair generation process, // Diffie-Hellman parameters are created, too. KeyPairGenerator dhKeyPairGenerator = KeyPairGenerator.getInstance("DH"); dhKeyPairGenerator.initialize(1024); KeyPair dhKeyPair = dhKeyPairGenerator.generateKeyPair();

// ALICE: transmits her public key (in encoded format) to Bob. The encoded // key also contains her Diffie-Hellman parameters. byte[] dhPubKeyEncoded = dhKeyPair.getPublic().getEncoded(); // send to Bob

// ALICE: initiates her version of the key agreement protocol with her own // private value KeyAgreement dhKeyAgree = KeyAgreement.getInstance("DH"); dhKeyAgree.doPhase(1, dhKeyPair.getPrivate());

// Meanwhile, Bob has created his own Diffie-Hellman key pair. He has // initialized his key pair generator with the Diffie-Hellman parameters // that he retrieved from Alice's public key. // Bob sends his own public value (in encoded format) to Alice.

// ALICE: uses the appropriate key factory to convert the encoding of Bob's // key into a PublicKey KeyFactory dhKeyFactory = KeyFactory.getInstance("DH"); X509EncodedKeySpec dhBobPubKeySpec = new X509EncodedKeySpec (dhBobPubKeyEncoded); PublicKey dhBobPubKey = dhKeyFactory.generatePublic(dhBobPubKeySpec);

// ALICE: completes her version of the key agreement protocol dhKeyAgree.doPhase(2, dhBobPubKey);

// ALICE: generates the shared secret byte[] secret = dhKeyAgree.generateSecret();

E 4 D 7

The methods of KeyAgreement are divided into two groups:

KeyAgreement API (Application Program Interface)
These are the public methods which are visible to applications requesting key agreement functionality.
KeyAgreement SPI (Service Provider Interface)
These are the (abstract) methods that must be implemented by providers of key agreement protocols. Each method in this group is prefixed by the keyword engine, and is called by a correspondingly-named public API method. For example, engineGenerateSecret is called by generateSecret.
E 7

See Also:
AlgorithmParameterGenerator, AlgorithmParameters, KeyPairGenerator, KeyFactory, KeyGenerator, KeySpec, AlgorithmParameterSpec, DHPrivateKeySpec, DHPublicKeySpec, DHParameterSpec, DHGenParameterSpec

Constructor Index

 o D 7 KeyAgreement(String)
Creates a KeyAgreement object for the specified key agreement algorithm. E 7 I 7 KeyAgreement(KeyAgreementSpi, Provider, String)
Creates a KeyAgreement object. E 7

Method Index

 o doPhase(int, Key)
Executes the next phase phase of the key agreement protocol, using the provided key key.
 o D 7 engineDoPhase(int, Key)
SPI: Executes the next phase phase of the key agreement protocol, using the provided key key.
 o engineGenerateSecret()
SPI: Generates the shared secret and returns it in a new buffer.
 o engineGenerateSecret(byte[], int)
SPI: Generates the shared secret, and places it into the buffer sharedSecret, beginning at offset.
 o engineGetSecretSize()
SPI: Returns the length of the shared secret (in bits), or null if this key agreement has not yet been initialized.
 o engineInit(AlgorithmParameterSpec, SecureRandom)
SPI: Initializes this key agreement with a set of parameters and a source of randomness.
 o engineInit(SecureRandom)
SPI: Initializes this key agreement to get random bytes (if needed) from random.
 o E 7 generateSecret()
Generates the shared secret and returns it in a new buffer.
 o generateSecret(byte[], int)
Generates the shared secret, and places it into the buffer sharedSecret, beginning at offset.
 o getAlgorithm()
Returns the standard name of the key agreement algorithm.
 o getInstance(String)
Generates a KeyAgreement object for the specified key agreement algorithm.
 o getInstance(String, String)
Generates a KeyAgreement object for the specified key agreement algorithm from the specified provider.
 o getProvider()
Returns the provider of this KeyAgreement object.
 o D 7 getSecretSize()
Returns the length of the shared secret (in bytes).
 o E 7 init(AlgorithmParameterSpec)
Initializes this key agreement with a set of parameters.
 o init(AlgorithmParameterSpec, SecureRandom)
Initializes this key agreement with a set of parameters and a source of randomness.
 o init(SecureRandom)
Initializes this key agreement to get random bytes (if needed) from random.

Constructors

D 7  o E 7 I 7  o E 7 KeyAgreement
D 7
 protected KeyAgreement(String algorithm)
E 7
I 7
 protected KeyAgreement(KeyAgreementSpi keyAgreeSpi,
                        Provider provider,
                        String algorithm)
E 7
D 7
Creates a KeyAgreement object for the specified key agreement algorithm. E 7 I 7
Creates a KeyAgreement object. E 7

Parameters: D 7
algorithm - the standard name of the key agreement algorithm. See Appendix A in the E 5 I 5 "../guide/security/CryptoSpec.html"> E 5 D 6 Java Cryptography Architecture API Specification & Reference E 6 I 6 Java Cryptography Extension API Specification & Reference E 6 for information about standard algorithm names. E 7 I 7
keyAgreeSpi - the delegate
provider - the provider
algorithm - the algorithm E 7

Methods

 o getAlgorithm
 public final String getAlgorithm()
Returns the standard name of the key agreement algorithm. D 7 See Appendix A in the E 5 I 5 "../guide/security/CryptoSpec.html"> E 7 I 7 See Appendix A in the E 7 E 5 D 6 Java Cryptography Architecture API Specification & Reference E 6 I 6 Java Cryptography Extension API Specification & Reference E 6 for information about standard algorithm names.

Returns:
the standard algorithm name.
 o getInstance
D 7
 public static KeyAgreement getInstance(String algorithm) throws NoSuchAlgorithmException
E 7
I 7
 public static final KeyAgreement getInstance(String algorithm) throws NoSuchAlgorithmException
E 7
Generates a KeyAgreement object for the specified key agreement algorithm.

Parameters:
algorithm - the standard name of the requested key agreement algorithm. D 7 See Appendix A in the E 5 I 5 "../guide/security/CryptoSpec.html"> E 7 I 7 See Appendix A in the E 7 E 5 D 6 Java Cryptography Architecture API Specification & Reference E 6 I 6 Java Cryptography Extension API Specification & Reference E 6 for information about standard algorithm names.
Returns:
the new KeyAgreement object
Throws: NoSuchAlgorithmException
if the requested key agreement algorithm is not available
 o getInstance
D 7
 public static KeyAgreement getInstance(String algorithm,
                                        String provider) throws NoSuchAlgorithmException, NoSuchProviderException
E 7
I 7
 public static final KeyAgreement getInstance(String algorithm,
                                              String provider) throws NoSuchAlgorithmException, NoSuchProviderException
E 7
Generates a KeyAgreement object for the specified key agreement algorithm from the specified provider.

Parameters:
algorithm - the standard name of the requested key agreement algorithm. D 7 See Appendix A in the E 5 I 5 "../guide/security/CryptoSpec.html"> E 7 I 7 See Appendix A in the E 7 E 5 D 6 Java Cryptography Architecture API Specification & Reference E 6 I 6 Java Cryptography Extension API Specification & Reference E 6 for information about standard algorithm names.
provider - the name of the provider
Returns:
the new KeyAgreement object
Throws: NoSuchAlgorithmException
if the requested key agreement algorithm is not available from the provider
Throws: NoSuchProviderException
if the requested provider is not available
See Also:
Provider
 o getProvider
 public final Provider getProvider()
Returns the provider of this KeyAgreement object.

Returns: D 3
the provider of this KeyAgreement object, or null if the provider has not yet been set E 3 I 3
the provider of this KeyAgreement object E 3
 o init
D 7
 public void init(SecureRandom random)
E 7
I 7
 public final void init(SecureRandom random)
E 7
Initializes this key agreement to get random bytes (if needed) from random. If the underlying implementation does not require any random bytes, random is ignored.

Parameters:
random - the source of randomness
D 7  o engineInit
 protected abstract void engineInit(SecureRandom random)
SPI: Initializes this key agreement to get random bytes (if needed) from random.

Parameters:
random - the source of randomness
E 7  o init
D 7
 public void init(AlgorithmParameterSpec params) throws InvalidAlgorithmParameterException
E 7
I 7
 public final void init(AlgorithmParameterSpec params) throws InvalidAlgorithmParameterException
E 7
Initializes this key agreement with a set of parameters.

Parameters:
params - the key agreement parameters
Throws: InvalidAlgorithmParameterException
if the given parameters are inappropriate for this key agreement protocol
 o init
D 7
 public void init(AlgorithmParameterSpec params,
                  SecureRandom random) throws InvalidAlgorithmParameterException
E 7
I 7
 public final void init(AlgorithmParameterSpec params,
                        SecureRandom random) throws InvalidAlgorithmParameterException
E 7
Initializes this key agreement with a set of parameters and a source of randomness.

Parameters:
params - the key agreement parameters
random - the source of randomness
Throws: InvalidAlgorithmParameterException
if the given parameters are inappropriate for this key agreement protocol
D 7  o engineInit
 protected abstract void engineInit(AlgorithmParameterSpec params,
                                    SecureRandom random) throws InvalidAlgorithmParameterException
SPI: Initializes this key agreement with a set of parameters and a source of randomness.

Parameters:
params - the key agreement parameters
random - the source of randomness
Throws: InvalidAlgorithmParameterException
if the given parameters are inappropriate for this key agreement protocol
E 7  o doPhase
D 7
 public Key doPhase(int phase,
                    Key key) throws IllegalStateException, InvalidKeyException
E 7
I 7
 public final Key doPhase(int phase,
                          Key key) throws IllegalStateException, InvalidKeyException
E 7
Executes the next phase phase of the key agreement protocol, using the provided key key.

Parameters:
phase - the phase of the key agreement protocol to be executed
key - the key for this phase
Returns:
the key resulting from phase, or null if phase does not yield a key
Throws: IllegalStateException
if phase is inappropriate for this key agreement protocol, or does not correspond to the next phase in the protocol sequence
Throws: InvalidKeyException
if the given key is inappropriate for this key agreement protocol, or inappropriate for the specified phase phase
D 7  o engineDoPhase
 protected abstract Key engineDoPhase(int phase,
                                      Key key) throws IllegalStateException, InvalidKeyException
SPI: Executes the next phase phase of the key agreement protocol, using the provided key key.

Parameters:
phase - the phase of the key agreement protocol to be executed
key - the key for this phase
Returns:
the key resulting from phase, or null if phase does not yield a key
Throws: IllegalStateException
if phase is inappropriate for this key agreement protocol, or does not correspond to the next phase in the protocol sequence
Throws: InvalidKeyException
if the given key is inappropriate for this key agreement protocol, or inappropriate for the specified phase phase
E 7  o generateSecret
D 7
 public byte[] generateSecret() throws IllegalStateException
E 7
I 7
 public final byte[] generateSecret() throws IllegalStateException
E 7
Generates the shared secret and returns it in a new buffer.

The key agreement is reset to its initial state after this call.

Returns:
the new buffer with the shared secret
Throws: IllegalStateException
if this key agreement has not been completed yet
D 7  o engineGenerateSecret
 protected abstract byte[] engineGenerateSecret() throws IllegalStateException
SPI: Generates the shared secret and returns it in a new buffer.

The key agreement is reset to its initial state after this call.

Returns:
the new buffer with the shared secret
Throws: IllegalStateException
if this key agreement has not been completed yet
E 7  o generateSecret
D 7
 public int generateSecret(byte sharedSecret[],
                           int offset) throws IllegalStateException
E 7
I 7
 public final int generateSecret(byte sharedSecret[],
                                 int offset) throws IllegalStateException, ShortBufferException
E 7
Generates the shared secret, and places it into the buffer sharedSecret, beginning at offset. D 7

The key agreement is reset to its initial state after this call. E 7 I 7

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.

After this call has completed successfully, this KeyAgreement is reset to its initial state (uninitialized), and can be re-used for further key agreements. E 7

Parameters:
sharedSecret - the buffer for the shared secret
offset - the offset in sharedSecret where the shared secret will be stored
Returns:
the number of bytes placed into sharedSecret
Throws: IllegalStateException
if this key agreement has not been completed yet I 7
Throws: ShortBufferException
if the given output buffer is too small to hold the secret E 7
D 7  o engineGenerateSecret
 protected abstract int engineGenerateSecret(byte sharedSecret[],
                                             int offset) throws IllegalStateException
SPI: Generates the shared secret, and places it into the buffer sharedSecret, beginning at offset.

The key agreement is reset to its initial state after this call.

Parameters:
sharedSecret - the buffer for the shared secret
offset - the offset in sharedSecret where the shared secret will be stored
Returns:
the number of bytes placed into sharedSecret
Throws: IllegalStateException
if this key agreement has not been completed yet
 o getSecretSize
 public int getSecretSize()
Returns the length of the shared secret (in bytes).

Returns:
the length of the shared secret (in bytes)
 o engineGetSecretSize
 protected abstract int engineGetSecretSize()
SPI: Returns the length of the shared secret (in bits), or null if this key agreement has not yet been initialized.

Returns:
the length of the shared secret (in bits), or null if this key agreement has not yet been initialized.
E 7
D 4
All Packages  Class Hierarchy  This Package  Previous  Next  Index
E 4 I 4 D 7 All Packages Class Hierarchy This Package Previous Next Index E 7 I 7 All Packages Class Hierarchy This Package Previous Next Index E 7 E 4 E 1