gomp-20050608-branch/libjava/classpath/java/security/KeyFactory.java

   1 /* KeyFactory.java --- Key Factory Class
   2    Copyright (C) 1999, 2003, 2004  Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19 02110-1301 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package java.security;
  40
  41 import gnu.java.security.Engine;
  42
  43 import java.security.spec.InvalidKeySpecException;
  44 import java.security.spec.KeySpec;
  45
  46 /**
  47  * <p>Key factories are used to convert keys (opaque cryptographic keys of type
  48  * {@link Key}) into key specifications (transparent representations of the
  49  * underlying key material), and vice versa.</p>
  50  *
  51  * <p>Key factories are bi-directional. That is, they allow you to build an
  52  * opaque key object from a given key specification (key material), or to
  53  * retrieve the underlying key material of a key object in a suitable format.</p>
  54  *
  55  * <p>Multiple compatible key specifications may exist for the same key. For
  56  * example, a <i>DSA</i> public key may be specified using {@link
  57  * java.security.spec.DSAPublicKeySpec} or {@link
  58  * java.security.spec.X509EncodedKeySpec}. A key factory can be used to
  59  * translate between compatible key specifications.</p>
  60  *
  61  * <p>The following is an example of how to use a key factory in order to
  62  * instantiate a <i>DSA</i> public key from its encoding. Assume Alice has
  63  * received a digital signature from Bob. Bob also sent her his public key (in
  64  * encoded format) to verify his signature. Alice then performs the following
  65  * actions:
  66  *
  67  * <pre>
  68  *  X509EncodedKeySpec bobPubKeySpec = new X509EncodedKeySpec(bobEncodedPubKey);
  69  *  KeyFactory keyFactory = KeyFactory.getInstance("DSA");
  70  *  PublicKey bobPubKey = keyFactory.generatePublic(bobPubKeySpec);
  71  *  Signature sig = Signature.getInstance("DSA");
  72  *  sig.initVerify(bobPubKey);
  73  *  sig.update(data);
  74  *  sig.verify(signature);
  75  * </pre>
  76  *
  77  * @since 1.2
  78  * @see Key
  79  * @see PublicKey
  80  * @see PrivateKey
  81  * @see KeySpec
  82  * @see java.security.spec.DSAPublicKeySpec
  83  * @see java.security.spec.X509EncodedKeySpec
  84    @author Mark Benvenuto
  85  */
  86 public class KeyFactory
  87 {
  88   /** The service name for key factories. */
  89   private static final String KEY_FACTORY = "KeyFactory";
  90
  91   private KeyFactorySpi keyFacSpi;
  92   private Provider provider;
  93   private String algorithm;
  94
  95   /**
  96    * Creates a <code>KeyFactory</code> object.
  97    *
  98    * @param keyFacSpi the delegate.
  99    * @param provider the provider.
 100    * @param algorithm the name of the algorithm to associate with this
 101    * <code>KeyFactory</code>.
 102    */
 103   protected KeyFactory(KeyFactorySpi keyFacSpi, Provider provider,
 104                        String algorithm)
 105   {
 106     this.keyFacSpi = keyFacSpi;
 107     this.provider = provider;
 108     this.algorithm = algorithm;
 109   }
 110
 111   /**
 112    * Generates a <code>KeyFactory</code> object that implements the specified
 113    * algorithm. If the default provider package provides an implementation of
 114    * the requested algorithm, an instance of <code>KeyFactory</code> containing
 115    * that implementation is returned. If the algorithm is not available in the
 116    * default package, other packages are searched.
 117    *
 118    * @param algorithm the name of the requested key algorithm. See Appendix A
 119    * in the Java Cryptography Architecture API Specification &amp; Reference
 120    * for information about standard algorithm names.
 121    * @return a <code>KeyFactory</code> object for the specified algorithm.
 122    * @throws NoSuchAlgorithmException if the requested algorithm is not
 123    * available in the default provider package or any of the other provider
 124    * packages that were searched.
 125    */
 126   public static KeyFactory getInstance(String algorithm)
 127     throws NoSuchAlgorithmException
 128   {
 129     Provider[] p = Security.getProviders();
 130     for (int i = 0; i < p.length; i++)
 131       try
 132         {
 133           return getInstance(algorithm, p[i]);
 134         }
 135       catch (NoSuchAlgorithmException e)
 136         {
 137           // Ignore.
 138         }
 139
 140     throw new NoSuchAlgorithmException(algorithm);
 141   }
 142
 143   /**
 144    * Generates a <code>KeyFactory</code> object for the specified algorithm
 145    * from the specified provider.
 146    *
 147    * @param algorithm the name of the requested key algorithm. See Appendix A
 148    * in the Java Cryptography Architecture API Specification &amp; Reference
 149    * for information about standard algorithm names.
 150    * @param provider the name of the provider.
 151    * @return a <code>KeyFactory</code> object for the specified algorithm.
 152    * @throws NoSuchAlgorithmException if the algorithm is not available from
 153    * the specified provider.
 154    * @throws NoSuchProviderException if the provider has not been configured.
 155    * @throws IllegalArgumentException if the provider name is null or empty.
 156    * @see Provider
 157    */
 158   public static KeyFactory getInstance(String algorithm, String provider)
 159     throws NoSuchAlgorithmException, NoSuchProviderException
 160   {
 161     if (provider == null || provider.length() == 0)
 162       throw new IllegalArgumentException("Illegal provider");
 163
 164     Provider p = Security.getProvider(provider);
 165     if (p == null)
 166       throw new NoSuchProviderException(provider);
 167
 168     return getInstance(algorithm, p);
 169   }
 170
 171   /**
 172    * Generates a <code>KeyFactory</code> object for the specified algorithm from
 173    * the specified provider. Note: the <code>provider</code> doesn't have to be
 174    * registered.
 175    *
 176    * @param algorithm the name of the requested key algorithm. See Appendix A
 177    * in the Java Cryptography Architecture API Specification &amp; Reference for
 178    * information about standard algorithm names.
 179    * @param provider the provider.
 180    * @return a <code>KeyFactory</code> object for the specified algorithm.
 181    * @throws NoSuchAlgorithmException if the algorithm is not available from
 182    * the specified provider.
 183    * @throws IllegalArgumentException if the <code>provider</code> is
 184    * <code>null</code>.
 185    * @since 1.4
 186    * @see Provider
 187    */
 188   public static KeyFactory getInstance(String algorithm, Provider provider)
 189     throws NoSuchAlgorithmException
 190   {
 191     if (provider == null)
 192       throw new IllegalArgumentException("Illegal provider");
 193
 194     try
 195       {
 196         return new KeyFactory((KeyFactorySpi)
 197           Engine.getInstance(KEY_FACTORY, algorithm, provider),
 198           provider, algorithm);
 199       }
 200     catch (java.lang.reflect.InvocationTargetException ite)
 201       {
 202         throw new NoSuchAlgorithmException(algorithm);
 203       }
 204     catch (ClassCastException cce)
 205       {
 206         throw new NoSuchAlgorithmException(algorithm);
 207       }
 208   }
 209
 210   /**
 211    * Returns the provider of this key factory object.
 212    *
 213    * @return the provider of this key factory object.
 214    */
 215   public final Provider getProvider()
 216   {
 217     return provider;
 218   }
 219
 220   /**
 221    * Gets the name of the algorithm associated with this <code>KeyFactory</code>.
 222    *
 223    * @return the name of the algorithm associated with this
 224    * <code>KeyFactory</code>.
 225    */
 226   public final String getAlgorithm()
 227   {
 228     return algorithm;
 229   }
 230
 231   /**
 232    * Generates a public key object from the provided key specification (key
 233    * material).
 234    *
 235    * @param keySpec the specification (key material) of the public key.
 236    * @return the public key.
 237    * @throws InvalidKeySpecException if the given key specification is
 238    * inappropriate for this key factory to produce a public key.
 239    */
 240   public final PublicKey generatePublic(KeySpec keySpec)
 241     throws InvalidKeySpecException
 242   {
 243     return keyFacSpi.engineGeneratePublic(keySpec);
 244   }
 245
 246   /**
 247    * Generates a private key object from the provided key specification (key
 248    * material).
 249    *
 250    * @param keySpec the specification (key material) of the private key.
 251    * @return the private key.
 252    * @throws InvalidKeySpecException if the given key specification is
 253    * inappropriate for this key factory to produce a private key.
 254    */
 255   public final PrivateKey generatePrivate(KeySpec keySpec)
 256     throws InvalidKeySpecException
 257   {
 258     return keyFacSpi.engineGeneratePrivate(keySpec);
 259   }
 260
 261   /**
 262    * Returns a specification (key material) of the given key object.
 263    * <code>keySpec</code> identifies the specification class in which the key
 264    * material should be returned. It could, for example, be
 265    * <code>DSAPublicKeySpec.class</code>, to indicate that the key material
 266    * should be returned in an instance of the {@link
 267    * java.security.spec.DSAPublicKeySpec} class.
 268    *
 269    * @param key the key.
 270    * @param keySpec the specification class in which the key material should be
 271    * returned.
 272    * @return the underlying key specification (key material) in an instance of
 273    * the requested specification class.
 274    * @throws InvalidKeySpecException if the requested key specification is
 275    * inappropriate for the given key, or the given key cannot be processed
 276    * (e.g., the given key has an unrecognized algorithm or format).
 277    */
 278   public final KeySpec getKeySpec(Key key, Class keySpec)
 279     throws InvalidKeySpecException
 280   {
 281     return keyFacSpi.engineGetKeySpec(key, keySpec);
 282   }
 283
 284   /**
 285    * Translates a key object, whose provider may be unknown or potentially
 286    * untrusted, into a corresponding key object of this key factory.
 287    *
 288    * @param key the key whose provider is unknown or untrusted.
 289    * @return the translated key.
 290    * @throws InvalidKeyException if the given key cannot be processed by this
 291    * key factory.
 292    */
 293   public final Key translateKey(Key key) throws InvalidKeyException
 294   {
 295     return keyFacSpi.engineTranslateKey(key);
 296   }
 297 }