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
See Also:
KeyGenerator, SecretKey

Constructor Summary

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 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.

Methods inherited from class java.lang.Object

clone, equals, extends Object> getClass, finalize, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

KeyAgreement

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

Method Details

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.

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.

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.

KeyAgreement.java -- Engine for key agreement methods. Copyright (C) 2004 Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.