This class provides an API to a key-agreement protocol that allows two or more parties to agree on a secret key without exchanging any secrets and in such a way that an eavesdropper listening in on the communication between those parties cannot determine the secret key. The KeyAgreement class is algorithm-independent and provider-based, so you must obtain a KeyAgreement object by calling one of the static getInstance( ) factory methods and specifying the name of the desired key agreement algorithm and, optionally, the name of the desired provider of that algorithm. The "SunJCE" provider implements a single key-agreement algorithm named "DiffieHellman".

To use a KeyAgreement object, each party first calls the init( ) method and supplies a Key object of its own. Then, each party obtains a Key object from one of the other parties to the agreement and calls doPhase( ). Each party obtains an intermediate Key object as the return value of doPhase( ), and these keys are again exchanged and passed to doPhase( ). This process typically repeats n-1 times, where n is the number of parties, but the actual number of repetitions is algorithm-dependent. When doPhase( ) is called the last time, the second argument must be TRue to indicate that it is the last phase of the agreement. After all calls to doPhase( ) have been made, each party calls generateSecret( ) to obtain an array of bytes or a SecretKey object for a named algorithm type. All parties obtain the same bytes or SecretKey from this method. The KeyAgreement class is not responsible for the transfer of Key objects between parties or for mutual authentication among the parties. These tasks must be accomplished through some external mechanism.

The most common type of key agreement is "DiffieHellman" key agreement between two parties. It proceeds as follows. First, both parties obtain a java.security.KeyPairGenerator for the "DiffieHellman" algorithm and use it to generate a java.security.KeyPair of Diffie-Hellman public and private keys. Each party passes its private key to the init( ) method of its KeyAgreement object. (The init( ) method can be passed a java.security.spec.AlgorithmParameterSpec object, but the Diffie-Hellman protocol does not require any additional parameters.) Next, the two parties exchange public keys, typically through some kind of networking mechanism (the KeyAgreement class is not responsible for the actual exchange of keys). Each party passes the public key of the other party to the doPhase( ) method of its KeyAgreement object. There are only two parties to this agreement, so only one phase is required, and the second argument to doPhase( ) is true. At this point, both parties call generateSecret( ) to obtain the shared secret key.

A three-party Diffie-Hellman key agreement requires two phases and is slightly more complicated. Let's call the three parties Alice, Bob, and Carol. Each generates a key pair and uses its private key to initialize its KeyAgreement object, as before. Then Alice passes her public key to Bob, Bob passes his to Carol, and Carol passes hers to Alice. Each party passes this public key to doPhase( ). Since this is not the final doPhase( ), the second argument is false, and doPhase( ) returns an intermediate Key object. The three parties exchange these intermediate keys again in the same way: Alice to Bob, Bob to Carol, and Carol to Alice. Now each party passes the intermediate key it has received to doPhase( ) a second time, passing true to indicate that this is the final phase. Finally, all three can call generateSecret( ) to obtain a shared key to encrypt future communication.

public class KeyAgreement {
// Protected Constructors
     protected KeyAgreement(KeyAgreementSpi keyAgreeSpi, java.security.Provider provider, 
        String algorithm);  
// Public Class Methods
     public static final KeyAgreement getInstance(String algorithm) 
        throws java.security.NoSuchAlgorithmException;  
     public static final KeyAgreement getInstance(String algorithm, String provider) 
        throws java.security.NoSuchAlgorithmException, 
        java.security.NoSuchProviderException;  
     public static final KeyAgreement getInstance(String algorithm, java.security.
        Provider provider) throws java.security.NoSuchAlgorithmException;  
// Public Instance Methods
     public final java.security.Key doPhase(java.security.Key key, boolean lastPhase) 
        throws java.security.InvalidKeyException, IllegalStateException;  
     public final byte[ ] generateSecret( ) throws IllegalStateException;  
     public final SecretKey generateSecret(String algorithm) 
        throws IllegalStateException, java.security.NoSuchAlgorithmException, 
        java.security.InvalidKeyException;  
     public final int generateSecret(byte[ ] sharedSecret, int offset) 
        throws IllegalStateException, ShortBufferException;  
     public final String getAlgorithm( );  
     public final java.security.Provider getProvider( );  
     public final void init(java.security.Key key) throws java.security.InvalidKeyException;  
     public final void init(java.security.Key key, java.security.SecureRandom random) 
        throws java.security.InvalidKeyException;  
     public final void init(java.security.Key key, java.security.spec
        .AlgorithmParameterSpec params) 
        throws java.security.InvalidKeyException, 
        java.security.InvalidAlgorithmParameterException;  
     public final void init(java.security.Key key, java.security.spec
        .AlgorithmParameterSpec params, 
        java.security.SecureRandom random) 
        throws java.security.InvalidKeyException, 
        java.security.InvalidAlgorithmParameterException;  
}