001/* KeyFactorySpi.java --- Key Factory Service Provider Interface
002   Copyright (C) 1999, 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 java.security;
040
041import java.security.spec.InvalidKeySpecException;
042import java.security.spec.KeySpec;
043
044/**
045 * KeyFactorySpi is the Service Provider Interface (SPI) for the 
046 * KeyFactory class. This is the interface for providers to 
047 * supply to implement a key factory for an algorithm.
048 *
049 * Key factories are used to convert keys (opaque cryptographic 
050 * keys of type Key) into key specifications (transparent 
051 * representations of the underlying key material).
052 *
053 * Key factories are bi-directional. They allow a key class 
054 * to be converted into a key specification (key material) and
055 * back again.
056 *
057 * For example DSA public keys can be specified as 
058 * DSAPublicKeySpec or X509EncodedKeySpec. The key factory
059 * translate these key specifications. 
060 *
061 * @since JDK 1.2
062 * @author Mark Benvenuto
063 */
064public abstract class KeyFactorySpi
065{
066  /**
067   * Constucts a new KeyFactorySpi.
068   */
069  public KeyFactorySpi()
070  {
071  }
072
073  /**
074   * Generates a public key from the provided key specification.
075   *
076   * @param keySpec key specification
077   *
078   * @return the public key
079   *
080   * @throws InvalidKeySpecException invalid key specification for
081   * this key factory to produce a public key
082   */
083  protected abstract PublicKey engineGeneratePublic(KeySpec keySpec)
084    throws InvalidKeySpecException;
085
086
087  /**
088   * Generates a private key from the provided key specification.
089   *
090   * @param keySpec key specification
091   *
092   * @return the private key
093   *
094   * @throws InvalidKeySpecException invalid key specification for
095   * this key factory to produce a private key
096   */
097  protected abstract PrivateKey engineGeneratePrivate(KeySpec keySpec)
098    throws InvalidKeySpecException;
099
100  /**
101   * Returns a key specification for the given key. keySpec 
102   * identifies the specification class to return the key 
103   * material in.
104   *
105   * @param key the key
106   * @param keySpec the specification class to return the 
107   * key material in.
108   *
109   * @return the key specification in an instance of the requested
110   * specification class
111   *
112   * @throws InvalidKeySpecException the requested key specification
113   * is inappropriate for this key or the key is 
114   * unrecognized.
115   */
116  protected abstract <T extends KeySpec> T engineGetKeySpec(Key key,
117                                                            Class<T> keySpec)
118    throws InvalidKeySpecException;
119
120
121  /**
122   * Translates the key from an unknown or untrusted provider
123   * into a key for this key factory.
124   *
125   * @param key key from an unknown or untrusted provider
126   *
127   * @return the translated key
128   *
129   * @throws InvalidKeyException if the key cannot be 
130   * processed by this key factory
131   */
132  protected abstract Key engineTranslateKey(Key key)
133    throws InvalidKeyException;
134}