001/* KeyAgreement.java -- Engine for key agreement methods.
002   Copyright (C) 2004  Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038
039package javax.crypto;
040
041import gnu.java.security.Engine;
042
043import java.lang.reflect.InvocationTargetException;
044import java.security.InvalidAlgorithmParameterException;
045import java.security.InvalidKeyException;
046import java.security.Key;
047import java.security.NoSuchAlgorithmException;
048import java.security.NoSuchProviderException;
049import java.security.Provider;
050import java.security.SecureRandom;
051import java.security.Security;
052import java.security.spec.AlgorithmParameterSpec;
053
054/**
055 * Key agreement is a method in which two or more parties may agree on a
056 * secret key for symmetric cryptography or message authentication
057 * without transmitting any secrets in the clear. Key agreement
058 * algorithms typically use a public/private <i>key pair</i>, and the
059 * public key (along with some additional information) is sent across
060 * untrusted networks.
061 *
062 * <p>The most common form of key agreement used today is the
063 * <i>Diffie-Hellman key exchange algorithm</i>, described in <a
064 * href="http://www.rsasecurity.com/rsalabs/pkcs/pkcs-3/">PKCS #3 -
065 * Diffie Hellman Key Agreement Standard</a>.
066 *
067 * @author Casey Marshall (csm@gnu.org)
068 * @since 1.4
069 * @see KeyGenerator
070 * @see SecretKey
071 */
072public class KeyAgreement
073{
074
075  // Fields.
076  // ------------------------------------------------------------------------
077
078  private static final String SERVICE = "KeyAgreement";
079
080  /** The underlying key agreement implementation. */
081  private KeyAgreementSpi kaSpi;
082
083  /** The provider of this implementation. */
084  private Provider provider;
085
086  /** The name of this instance's algorithm. */
087  private String algorithm;
088
089  /** Singnals whether or not this instance has been initialized. */
090  private boolean virgin;
091
092  // Constructor.
093  // ------------------------------------------------------------------------
094
095  protected KeyAgreement(KeyAgreementSpi kaSpi, Provider provider,
096                         String algorithm)
097  {
098    this.kaSpi = kaSpi;
099    this.provider = provider;
100    this.algorithm = algorithm;
101    virgin = true;
102  }
103
104  /**
105   * Get an implementation of an algorithm from the first provider that
106   * implements it.
107   * 
108   * @param algorithm The name of the algorithm to get.
109   * @return The proper KeyAgreement instacne, if found.
110   * @throws NoSuchAlgorithmException If the specified algorithm is not
111   *           implemented by any installed provider.
112   * @throws IllegalArgumentException if <code>algorithm</code> is
113   *           <code>null</code> or is an empty string.
114   */
115  public static final KeyAgreement getInstance(String algorithm)
116      throws NoSuchAlgorithmException
117  {
118    Provider[] p = Security.getProviders();
119    NoSuchAlgorithmException lastException = null;
120    for (int i = 0; i < p.length; i++)
121      try
122        {
123          return getInstance(algorithm, p[i]);
124        }
125      catch (NoSuchAlgorithmException x)
126        {
127          lastException = x;
128        }
129    if (lastException != null)
130      throw lastException;
131    throw new NoSuchAlgorithmException(algorithm);
132  }
133
134  /**
135   * Return an implementation of an algorithm from a named provider.
136   * 
137   * @param algorithm The name of the algorithm to create.
138   * @param provider The name of the provider from which to get the
139   *          implementation.
140   * @return The proper KeyAgreement instance, if found.
141   * @throws NoSuchAlgorithmException If the named provider does not implement
142   *           the algorithm.
143   * @throws NoSuchProviderException If the named provider does not exist.
144   * @throws IllegalArgumentException if either <code>algorithm</code> or
145   *           <code>provider</code> is <code>null</code>, or if
146   *           <code>algorithm</code> is an empty string.
147   */
148  public static final KeyAgreement getInstance(String algorithm, String provider)
149      throws NoSuchAlgorithmException, NoSuchProviderException
150  {
151    if (provider == null)
152      throw new IllegalArgumentException("provider MUST NOT be null");
153    Provider p = Security.getProvider(provider);
154    if (p == null)
155      throw new NoSuchProviderException(provider);
156    return getInstance(algorithm, p);
157  }
158
159  /**
160   * Return an implementation of an algorithm from a specific provider.
161   * 
162   * @param algorithm The name of the algorithm to get.
163   * @param provider The provider from which to get the implementation.
164   * @return The proper KeyAgreement instance, if found.
165   * @throws NoSuchAlgorithmException If this provider does not implement the
166   *           algorithm.
167   * @throws IllegalArgumentException if either <code>algorithm</code> or
168   *           <code>provider</code> is <code>null</code>, or if
169   *           <code>algorithm</code> is an empty string.
170   */
171  public static final KeyAgreement getInstance(String algorithm,
172                                               Provider provider)
173    throws NoSuchAlgorithmException
174  {
175    StringBuilder sb = new StringBuilder("KeyAgreement algorithm [")
176        .append(algorithm).append("] from provider[")
177        .append(provider).append("] could not be created");
178    Throwable cause;
179    try
180      {
181        Object spi = Engine.getInstance(SERVICE, algorithm, provider);
182        return new KeyAgreement((KeyAgreementSpi) spi, provider, algorithm);
183      }
184    catch (InvocationTargetException x)
185      {
186        cause = x.getCause();
187        if (cause instanceof NoSuchAlgorithmException)
188          throw (NoSuchAlgorithmException) cause;
189        if (cause == null)
190          cause = x;
191      }
192    catch (ClassCastException x)
193      {
194        cause = x;
195      }
196    NoSuchAlgorithmException x = new NoSuchAlgorithmException(sb.toString());
197    x.initCause(cause);
198    throw x;
199  }
200
201  /**
202   * Do a phase in the key agreement. The number of times this method is
203   * called depends upon the algorithm and the number of parties
204   * involved, but must be called at least once with the
205   * <code>lastPhase</code> flag set to <code>true</code>.
206   *
207   * @param key       The key for this phase.
208   * @param lastPhase Should be <code>true</code> if this will be the
209   *        last phase before generating the shared secret.
210   * @return The intermediate result, or <code>null</code> if there is
211   *         no intermediate result.
212   * @throws java.lang.IllegalStateException If this instance has not
213   *         been initialized.
214   * @throws java.security.InvalidKeyException If the key is
215   *         inappropriate for this algorithm.
216   */
217  public final Key doPhase(Key key, boolean lastPhase)
218    throws IllegalStateException, InvalidKeyException
219  {
220    if (virgin)
221      {
222        throw new IllegalStateException("not initialized");
223      }
224    return kaSpi.engineDoPhase(key, lastPhase);
225  }
226
227  /**
228   * Generate the shared secret in a new byte array.
229   *
230   * @return The shared secret.
231   * @throws java.lang.IllegalStateException If this instnace has not
232   *         been initialized, or if not enough calls to
233   *         <code>doPhase</code> have been made.
234   */
235  public final byte[] generateSecret() throws IllegalStateException
236  {
237    if (virgin)
238      {
239        throw new IllegalStateException("not initialized");
240      }
241    return kaSpi.engineGenerateSecret();
242  }
243
244  /**
245   * Generate the shared secret and store it into the supplied array.
246   *
247   * @param sharedSecret The array in which to store the secret.
248   * @param offset       The index in <code>sharedSecret</code> to start
249   *                     storing data.
250   * @return The length of the shared secret, in bytes.
251   * @throws java.lang.IllegalStateException If this instnace has not
252   *         been initialized, or if not enough calls to
253   *         <code>doPhase</code> have been made.
254   * @throws javax.crypto.ShortBufferException If the supplied array is
255   *         not large enough to store the result.
256   */
257  public final int generateSecret(byte[] sharedSecret, int offset)
258  throws IllegalStateException, ShortBufferException
259  {
260    if (virgin)
261      {
262        throw new IllegalStateException("not initialized");
263      }
264    return kaSpi.engineGenerateSecret(sharedSecret, offset);
265  }
266
267  /**
268   * Generate the shared secret and return it as an appropriate {@link
269   * SecretKey}.
270   *
271   * @param algorithm The secret key's algorithm.
272   * @return The shared secret as a secret key.
273   * @throws java.lang.IllegalStateException If this instnace has not
274   *         been initialized, or if not enough calls to
275   *         <code>doPhase</code> have been made.
276   * @throws java.security.InvalidKeyException If the shared secret
277   *         cannot be used to make a {@link SecretKey}.
278   * @throws java.security.NoSuchAlgorithmException If the specified
279   *         algorithm does not exist.
280   */
281  public final SecretKey generateSecret(String algorithm)
282  throws IllegalStateException, InvalidKeyException, NoSuchAlgorithmException
283  {
284    if (virgin)
285      {
286        throw new IllegalStateException("not initialized");
287      }
288    return kaSpi.engineGenerateSecret(algorithm);
289  }
290
291  /**
292   * Return the name of this key-agreement algorithm.
293   *
294   * @return The algorithm name.
295   */
296  public final String getAlgorithm()
297  {
298    return algorithm;
299  }
300
301  /**
302   * Return the provider of the underlying implementation.
303   *
304   * @return The provider.
305   */
306  public final Provider getProvider()
307  {
308    return provider;
309  }
310
311  /**
312   * Initialize this key agreement with a key. This method will use the
313   * highest-priority {@link java.security.SecureRandom} as its source
314   * of randomness.
315   *
316   * @param key The key, usually the user's private key.
317   * @throws java.security.InvalidKeyException If the supplied key is
318   *         not appropriate.
319   */
320  public final void init(Key key) throws InvalidKeyException
321  {
322    init(key, new SecureRandom());
323  }
324
325  /**
326   * Initialize this key agreement with a key and a source of
327   * randomness.
328   *
329   * @param key    The key, usually the user's private key.
330   * @param random The source of randomness.
331   * @throws java.security.InvalidKeyException If the supplied key is
332   *         not appropriate.
333   */
334  public final void init(Key key, SecureRandom random)
335    throws InvalidKeyException
336  {
337    kaSpi.engineInit(key, random);
338    virgin = false; // w00t!
339  }
340
341  /**
342   * Initialize this key agreement with a key and parameters. This
343   * method will use the highest-priority {@link
344   * java.security.SecureRandom} as its source of randomness.
345   *
346   * @param key    The key, usually the user's private key.
347   * @param params The algorithm parameters.
348   * @throws java.security.InvalidAlgorithmParameterException If the
349   *         supplied parameters are not appropriate.
350   * @throws java.security.InvalidKeyException If the supplied key is
351   *         not appropriate.
352   */
353  public final void init(Key key, AlgorithmParameterSpec params)
354    throws InvalidAlgorithmParameterException, InvalidKeyException
355  {
356    init(key, params, new SecureRandom());
357  }
358
359  /**
360   * Initialize this key agreement with a key, parameters, and source of
361   * randomness.
362   *
363   * @param key    The key, usually the user's private key.
364   * @param params The algorithm parameters.
365   * @param random The source of randomness.
366   * @throws java.security.InvalidAlgorithmParameterException If the
367   *         supplied parameters are not appropriate.
368   * @throws java.security.InvalidKeyException If the supplied key is
369   *         not appropriate.
370   */
371  public final void init(Key key, AlgorithmParameterSpec params,
372                         SecureRandom random)
373    throws InvalidAlgorithmParameterException, InvalidKeyException
374  {
375    kaSpi.engineInit(key, params, random);
376    virgin = false; // w00t!
377  }
378}