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