Source for java.security.KeyFactory

   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: }