toolchain/gcc/libjava/java/security/KeyFactory.java

   1 /* KeyFactory.java --- Key Factory Class
   2    Copyright (C) 1999, 2003 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., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 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 package java.security;
  39
  40 import java.security.spec.KeySpec;
  41 import java.security.spec.InvalidKeySpecException;
  42 import java.security.NoSuchAlgorithmException;
  43
  44 import gnu.java.security.Engine;
  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 ignored) {}
 136
 137     throw new NoSuchAlgorithmException(algorithm);
 138   }
 139
 140   /**
 141    * Generates a <code>KeyFactory</code> object for the specified algorithm
 142    * from the specified provider.
 143    *
 144    * @param algorithm the name of the requested key algorithm. See Appendix A
 145    * in the Java Cryptography Architecture API Specification &amp; Reference
 146    * for information about standard algorithm names.
 147    * @param provider the name of the provider.
 148    * @return a <code>KeyFactory</code> object for the specified algorithm.
 149    * @throws NoSuchAlgorithmException if the algorithm is not available from
 150    * the specified provider.
 151    * @throws NoSuchProviderException if the provider has not been configured.
 152    * @throws IllegalArgumentException if the provider name is null or empty.
 153    * @see Provider
 154    */
 155   public static KeyFactory getInstance(String algorithm, String provider)
 156     throws NoSuchAlgorithmException, NoSuchProviderException
 157   {
 158     if (provider == null || provider.length() == 0)
 159       throw new IllegalArgumentException("Illegal provider");
 160
 161     Provider p = Security.getProvider(provider);
 162     if (p == null)
 163       throw new NoSuchProviderException();
 164
 165     return getInstance(algorithm, p);
 166   }
 167
 168   /**
 169    * Generates a <code>KeyFactory</code> object for the specified algorithm from
 170    * the specified provider. Note: the <code>provider</code> doesn't have to be
 171    * registered.
 172    *
 173    * @param algorithm the name of the requested key algorithm. See Appendix A
 174    * in the Java Cryptography Architecture API Specification &amp; Reference for
 175    * information about standard algorithm names.
 176    * @param provider the provider.
 177    * @return a <code>KeyFactory</code> object for the specified algorithm.
 178    * @throws NoSuchAlgorithmException if the algorithm is not available from
 179    * the specified provider.
 180    * @throws IllegalArgumentException if the <code>provider</code> is
 181    * <code>null</code>.
 182    * @since 1.4
 183    * @see Provider
 184    */
 185   public static KeyFactory getInstance(String algorithm, Provider provider)
 186     throws NoSuchAlgorithmException
 187   {
 188     if (provider == null)
 189       throw new IllegalArgumentException("Illegal provider");
 190
 191     try
 192       {
 193         return new KeyFactory((KeyFactorySpi)
 194           Engine.getInstance(KEY_FACTORY, algorithm, provider),
 195           provider, algorithm);
 196       }
 197     catch (java.lang.reflect.InvocationTargetException ite)
 198       {
 199         throw new NoSuchAlgorithmException(algorithm);
 200       }
 201     catch (ClassCastException cce)
 202       {
 203         throw new NoSuchAlgorithmException(algorithm);
 204       }
 205   }
 206
 207   /**
 208    * Returns the provider of this key factory object.
 209    *
 210    * @return the provider of this key factory object.
 211    */
 212   public final Provider getProvider()
 213   {
 214     return provider;
 215   }
 216
 217   /**
 218    * Gets the name of the algorithm associated with this <code>KeyFactory</code>.
 219    *
 220    * @return the name of the algorithm associated with this
 221    * <code>KeyFactory</code>.
 222    */
 223   public final String getAlgorithm()
 224   {
 225     return algorithm;
 226   }
 227
 228   /**
 229    * Generates a public key object from the provided key specification (key
 230    * material).
 231    *
 232    * @param keySpec the specification (key material) of the public key.
 233    * @return the public key.
 234    * @throws InvalidKeySpecException if the given key specification is
 235    * inappropriate for this key factory to produce a public key.
 236    */
 237   public final PublicKey generatePublic(KeySpec keySpec)
 238     throws InvalidKeySpecException
 239   {
 240     return keyFacSpi.engineGeneratePublic(keySpec);
 241   }
 242
 243   /**
 244    * Generates a private key object from the provided key specification (key
 245    * material).
 246    *
 247    * @param keySpec the specification (key material) of the private key.
 248    * @return the private key.
 249    * @throws InvalidKeySpecException if the given key specification is
 250    * inappropriate for this key factory to produce a private key.
 251    */
 252   public final PrivateKey generatePrivate(KeySpec keySpec)
 253     throws InvalidKeySpecException
 254   {
 255     return keyFacSpi.engineGeneratePrivate(keySpec);
 256   }
 257
 258   /**
 259    * Returns a specification (key material) of the given key object.
 260    * <code>keySpec</code> identifies the specification class in which the key
 261    * material should be returned. It could, for example, be
 262    * <code>DSAPublicKeySpec.class</code>, to indicate that the key material
 263    * should be returned in an instance of the {@link
 264    * java.security.spec.DSAPublicKeySpec} class.
 265    *
 266    * @param key the key.
 267    * @param keySpec the specification class in which the key material should be
 268    * returned.
 269    * @return the underlying key specification (key material) in an instance of
 270    * the requested specification class.
 271    * @throws InvalidKeySpecException if the requested key specification is
 272    * inappropriate for the given key, or the given key cannot be processed
 273    * (e.g., the given key has an unrecognized algorithm or format).
 274    */
 275   public final KeySpec getKeySpec(Key key, Class keySpec)
 276     throws InvalidKeySpecException
 277   {
 278     return keyFacSpi.engineGetKeySpec(key, keySpec);
 279   }
 280
 281   /**
 282    * Translates a key object, whose provider may be unknown or potentially
 283    * untrusted, into a corresponding key object of this key factory.
 284    *
 285    * @param key the key whose provider is unknown or untrusted.
 286    * @return the translated key.
 287    * @throws InvalidKeyException if the given key cannot be processed by this
 288    * key factory.
 289    */
 290   public final Key translateKey(Key key) throws InvalidKeyException
 291   {
 292     return keyFacSpi.engineTranslateKey(key);
 293   }
 294 }