001 /*
002 * Copyright 1997-2004 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.security;
027
028 import java.security.spec.KeySpec;
029 import java.security.spec.InvalidKeySpecException;
030
031 /**
032 * This class defines the <i>Service Provider Interface</i> (<b>SPI</b>)
033 * for the <code>KeyFactory</code> class.
034 * All the abstract methods in this class must be implemented by each
035 * cryptographic service provider who wishes to supply the implementation
036 * of a key factory for a particular algorithm.
037 *
038 * <P> Key factories are used to convert <I>keys</I> (opaque
039 * cryptographic keys of type <code>Key</code>) into <I>key specifications</I>
040 * (transparent representations of the underlying key material), and vice
041 * versa.
042 *
043 * <P> Key factories are bi-directional. That is, they allow you to build an
044 * opaque key object from a given key specification (key material), or to
045 * retrieve the underlying key material of a key object in a suitable format.
046 *
047 * <P> Multiple compatible key specifications may exist for the same key.
048 * For example, a DSA public key may be specified using
049 * <code>DSAPublicKeySpec</code> or
050 * <code>X509EncodedKeySpec</code>. A key factory can be used to translate
051 * between compatible key specifications.
052 *
053 * <P> A provider should document all the key specifications supported by its
054 * key factory.
055 *
056 * @author Jan Luehe
057 *
058 * @version 1.19, 05/05/07
059 *
060 * @see KeyFactory
061 * @see Key
062 * @see PublicKey
063 * @see PrivateKey
064 * @see java.security.spec.KeySpec
065 * @see java.security.spec.DSAPublicKeySpec
066 * @see java.security.spec.X509EncodedKeySpec
067 *
068 * @since 1.2
069 */
070
071 public abstract class KeyFactorySpi {
072
073 /**
074 * Generates a public key object from the provided key
075 * specification (key material).
076 *
077 * @param keySpec the specification (key material) of the public key.
078 *
079 * @return the public key.
080 *
081 * @exception InvalidKeySpecException if the given key specification
082 * is inappropriate for this key factory to produce a public key.
083 */
084 protected abstract PublicKey engineGeneratePublic(KeySpec keySpec)
085 throws InvalidKeySpecException;
086
087 /**
088 * Generates a private key object from the provided key
089 * specification (key material).
090 *
091 * @param keySpec the specification (key material) of the private key.
092 *
093 * @return the private key.
094 *
095 * @exception InvalidKeySpecException if the given key specification
096 * is inappropriate for this key factory to produce a private key.
097 */
098 protected abstract PrivateKey engineGeneratePrivate(KeySpec keySpec)
099 throws InvalidKeySpecException;
100
101 /**
102 * Returns a specification (key material) of the given key
103 * object.
104 * <code>keySpec</code> identifies the specification class in which
105 * the key material should be returned. It could, for example, be
106 * <code>DSAPublicKeySpec.class</code>, to indicate that the
107 * key material should be returned in an instance of the
108 * <code>DSAPublicKeySpec</code> class.
109 *
110 * @param key the key.
111 *
112 * @param keySpec the specification class in which
113 * the key material should be returned.
114 *
115 * @return the underlying key specification (key material) in an instance
116 * of the requested specification class.
117
118 * @exception InvalidKeySpecException if the requested key specification is
119 * inappropriate for the given key, or the given key cannot be dealt with
120 * (e.g., the given key has an unrecognized format).
121 */
122 protected abstract <T extends KeySpec> T engineGetKeySpec(Key key,
123 Class<T> keySpec) throws InvalidKeySpecException;
124
125 /**
126 * Translates a key object, whose provider may be unknown or
127 * potentially untrusted, into a corresponding key object of this key
128 * factory.
129 *
130 * @param key the key whose provider is unknown or untrusted.
131 *
132 * @return the translated key.
133 *
134 * @exception InvalidKeyException if the given key cannot be processed
135 * by this key factory.
136 */
137 protected abstract Key engineTranslateKey(Key key)
138 throws InvalidKeyException;
139
140 }
|