SecretKeyFactory


1   /*
2    * @(#)SecretKeyFactory.java    1.6 03/12/19
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7     
8   /*
9    * NOTE:
10   * Because of various external restrictions (i.e. US export
11   * regulations, etc.), the actual source code can not be provided
12   * at this time. This file represents the skeleton of the source
13   * file, so that javadocs of the API can be created.
14   */
15  
16  package javax.crypto;
17  
18  import java.util.*;
19  import java.security.*;
20  import java.security.spec.*;
21  import sun.security.jca.*;
22  
23  import java.security.Provider.Service;
24  import sun.security.jca.GetInstance.Instance;
25  
26  /** 
27   * This class represents a factory for secret keys.
28   *
29   * <P> Key factories are used to convert <I>keys</I> (opaque
30   * cryptographic keys of type <code>Key</code>) into <I>key specifications</I>
31   * (transparent representations of the underlying key material), and vice
32   * versa.
33   * Secret key factories operate only on secret (symmetric) keys.
34   *
35   * <P> Key factories are bi-directional, i.e., they allow to build an opaque
36   * key object from a given key specification (key material), or to retrieve
37   * the underlying key material of a key object in a suitable format.
38   *
39   * <P> Application developers should refer to their provider's documentation
40   * to find out which key specifications are supported by the
41   * {@link #generateSecret(java.security.spec.KeySpec) generateSecret} and
42   * {@link #getKeySpec(javax.crypto.SecretKey, java.lang.Class) getKeySpec} 
43   * methods.
44   * For example, the DES secret-key factory supplied by the "SunJCE" provider
45   * supports <code>DESKeySpec</code> as a transparent representation of DES
46   * keys, and that provider's secret-key factory for Triple DES keys supports
47   * <code>DESedeKeySpec</code> as a transparent representation of Triple DES
48   * keys.
49   *
50   * @author Jan Luehe
51   *
52   * @version 1.36, 10/29/03
53   *
54   * @see SecretKey
55   * @see javax.crypto.spec.DESKeySpec
56   * @see javax.crypto.spec.DESedeKeySpec
57   * @see javax.crypto.spec.PBEKeySpec
58   * @since 1.4
59   */
60  public class SecretKeyFactory
61  {
62  
63      /** 
64       * Creates a SecretKeyFactory object.
65       *
66       * @param keyFacSpi the delegate
67       * @param provider the provider
68       * @param algorithm the secret-key algorithm
69       */
70      protected SecretKeyFactory(SecretKeyFactorySpi keyFacSpi, Provider provider,
71          String algorithm)
72      { }
73  
74      /** 
75       * Generates a <code>SecretKeyFactory</code> object for the
76       * specified secret-key algorithm.
77       * If the default provider package provides an implementation of the
78       * requested factory, an instance of <code>SecretKeyFactory</code>
79       * containing that implementation is returned.
80       * If the requested factory is not available in the default provider
81       * package, other provider packages are searched.
82       *
83       * @param algorithm the standard name of the requested secret-key
84       * algorithm. 
85       * See Appendix A in the
86       * <a HREF="../../../guide/security/jce/JCERefGuide.html#AppA">
87       * Java Cryptography Extension Reference Guide</a> 
88       * for information about standard algorithm names.
89       *
90       * @return a <code>SecretKeyFactory</code> object for the specified
91       * secret-key algorithm.
92       *
93       * @exception NullPointerException if the specified algorithm 
94       * is null.
95       * @exception NoSuchAlgorithmException if a secret-key factory for
96       * the specified algorithm is not available in the default provider
97       * package or any of the other provider packages that were searched.  
98       */
99      public static final SecretKeyFactory getInstance(String algorithm)
100         throws NoSuchAlgorithmException
101     { }
102 
103     /** 
104      * Generates a <code>SecretKeyFactory</code> object for the specified
105      * secret-key algorithm from the specified provider.
106      *
107      * @param algorithm the standard name of the requested secret-key
108      * algorithm. 
109      * See Appendix A in the
110      * <a HREF="../../../guide/security/jce/JCERefGuide.html#AppA">
111      * Java Cryptography Extension Reference Guide</a> 
112      * for information about standard algorithm names.
113      * @param provider the name of the provider.
114      *
115      * @return a <code>SecretKeyFactory</code> object for the specified
116      * secret-key algorithm.
117      *
118      * @exception NoSuchAlgorithmException if a secret-key factory for the
119      * specified algorithm is not available from the specified provider.
120      *
121      * @exception NullPointerException if the specified algorithm 
122      * is null.
123      * @exception NoSuchProviderException if the specified provider has not
124      * been configured.
125      * @exception IllegalArgumentException if the <code>provider</code>
126      * is null.
127      */
128     public static final SecretKeyFactory getInstance(String algorithm, String
129         provider) throws NoSuchAlgorithmException, NoSuchProviderException
130     { }
131 
132     /** 
133      * Generates a <code>SecretKeyFactory</code> object for the specified
134      * secret-key algorithm from the specified provider. Note: the 
135      * <code>provider</code> doesn't have to be registered.
136      *
137      * @param algorithm the standard name of the requested secret-key
138      * algorithm. 
139      * See Appendix A in the
140      * <a HREF="../../../guide/security/jce/JCERefGuide.html#AppA">
141      * Java Cryptography Extension Reference Guide</a> 
142      * for information about standard algorithm names.
143      * @param provider the provider.
144      *
145      * @return a <code>SecretKeyFactory</code> object for the specified
146      * secret-key algorithm.
147      *
148      * @exception NullPointerException if the specified algorithm 
149      * is null.
150      * @exception NoSuchAlgorithmException if a secret-key factory for the
151      * specified algorithm is not available from the specified provider.
152      * @exception IllegalArgumentException if the <code>provider</code>
153      * is null.
154      */
155     public static final SecretKeyFactory getInstance(String algorithm, Provider
156         provider) throws NoSuchAlgorithmException
157     { }
158 
159     /** 
160      * Returns the provider of this <code>SecretKeyFactory</code> object.
161      * 
162      * @return the provider of this <code>SecretKeyFactory</code> object
163      */
164     public final Provider getProvider() { }
165 
166     /** 
167      * Returns the algorithm name of this <code>SecretKeyFactory</code> object.
168      *
169      * <p>This is the same name that was specified in one of the
170      * <code>getInstance</code> calls that created this
171      * <code>SecretKeyFactory</code> object.
172      * 
173      * @return the algorithm name of this <code>SecretKeyFactory</code>
174      * object. 
175      */
176     public final String getAlgorithm() { }
177 
178     /** 
179      * Generates a <code>SecretKey</code> object from the provided key
180      * specification (key material).
181      *
182      * @param keySpec the specification (key material) of the secret key
183      *
184      * @return the secret key
185      *
186      * @exception InvalidKeySpecException if the given key specification
187      * is inappropriate for this secret-key factory to produce a secret key.
188      */
189     public final SecretKey generateSecret(KeySpec keySpec)
190         throws InvalidKeySpecException
191     { }
192 
193     /** 
194      * Returns a specification (key material) of the given key object
195      * in the requested format.
196      *
197      * @param key the key 
198      * @param keySpec the requested format in which the key material shall be
199      * returned
200      *
201      * @return the underlying key specification (key material) in the
202      * requested format
203      *
204      * @exception InvalidKeySpecException if the requested key specification is
205      * inappropriate for the given key (e.g., the algorithms associated with
206      * <code>key</code> and <code>keySpec</code> do not match, or
207      * <code>key</code> references a key on a cryptographic hardware device
208      * whereas <code>keySpec</code> is the specification of a software-based
209      * key), or the given key cannot be dealt with
210      * (e.g., the given key has an algorithm or format not supported by this
211      * secret-key factory).
212      */
213     public final KeySpec getKeySpec(SecretKey key, Class keySpec)
214         throws InvalidKeySpecException
215     { }
216 
217     /** 
218      * Translates a key object, whose provider may be unknown or potentially
219      * untrusted, into a corresponding key object of this secret-key factory.
220      *
221      * @param key the key whose provider is unknown or untrusted
222      *
223      * @return the translated key
224      *
225      * @exception InvalidKeyException if the given key cannot be processed
226      * by this secret-key factory.
227      */
228     public final SecretKey translateKey(SecretKey key)
229         throws InvalidKeyException
230     { }
231 }
232
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Java Books Remove Frame
Popular Tags