KeyGenerator


1   /*
2    * @(#)KeyGenerator.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 provides the functionality of a (symmetric) key generator.
28   *
29   * <p>Key generators are constructed using one of the <code>getInstance</code>
30   * class methods of this class.
31   *
32   * <p>KeyGenerator objects are reusable, i.e., after a key has been
33   * generated, the same KeyGenerator object can be re-used to generate further
34   * keys.
35   *
36   * <p>There are two ways to generate a key: in an algorithm-independent
37   * manner, and in an algorithm-specific manner.
38   * The only difference between the two is the initialization of the object:
39   * 
40   * <ul>
41   * <li><b>Algorithm-Independent Initialization</b>
42   * <p>All key generators share the concepts of a <i>keysize</i> and a
43   * <i>source of randomness</i>.
44   * There is an 
45   * {@link #init(int, java.security.SecureRandom) init} 
46   * method in this KeyGenerator class that takes these two universally
47   * shared types of arguments. There is also one that takes just a
48   * <code>keysize</code> argument, and uses the SecureRandom implementation
49   * of the highest-priority installed provider as the source of randomness
50   * (or a system-provided source of randomness if none of the installed
51   * providers supply a SecureRandom implementation), and one that takes just a
52   * source of randomness.
53   * 
54   * <p>Since no other parameters are specified when you call the above
55   * algorithm-independent <code>init</code> methods, it is up to the
56   * provider what to do about the algorithm-specific parameters (if any) to be
57   * associated with each of the keys.
58   * <p>
59   *
60   * <li><b>Algorithm-Specific Initialization</b>
61   * <p>For situations where a set of algorithm-specific parameters already
62   * exists, there are two
63   * {@link #init(java.security.spec.AlgorithmParameterSpec) init}
64   * methods that have an <code>AlgorithmParameterSpec</code>
65   * argument. One also has a <code>SecureRandom</code> argument, while the
66   * other uses the SecureRandom implementation
67   * of the highest-priority installed provider as the source of randomness
68   * (or a system-provided source of randomness if none of the installed
69   * providers supply a SecureRandom implementation).
70   * </ul>
71   *
72   * <p>In case the client does not explicitly initialize the KeyGenerator
73   * (via a call to an <code>init</code> method), each provider must
74   * supply (and document) a default initialization.
75   *
76   * @author Jan Luehe
77   *
78   * @version 1.48, 10/29/03
79   *
80   * @see SecretKey
81   * @since 1.4
82   */
83  public class KeyGenerator
84  {
85  
86      /** 
87       * Creates a KeyGenerator object.
88       *
89       * @param keyGenSpi the delegate
90       * @param provider the provider
91       * @param algorithm the algorithm
92       */
93      protected KeyGenerator(KeyGeneratorSpi keyGenSpi, Provider provider, String
94          algorithm)
95      { }
96  
97      /** 
98       * Returns the algorithm name of this <code>KeyGenerator</code> object.
99       *
100      * <p>This is the same name that was specified in one of the
101      * <code>getInstance</code> calls that created this
102      * <code>KeyGenerator</code> object.
103      * 
104      * @return the algorithm name of this <code>KeyGenerator</code> object. 
105      */
106     public final String getAlgorithm() { }
107 
108     /** 
109      * Generates a <code>KeyGenerator</code> object for the specified
110      * algorithm.
111      * If the default provider package provides an implementation of the
112      * requested key generator, an instance of
113      * <code>KeyGenerator</code> containing that implementation is returned.
114      * If the requested key generator is not available in the default provider
115      * package, other provider packages are searched.
116      *
117      * @param algorithm the standard name of the requested key algorithm.
118      * See Appendix A in the
119      * <a HREF="../../../guide/security/jce/JCERefGuide.html#AppA">
120      * Java Cryptography Extension Reference Guide</a> 
121      * for information about standard algorithm names.
122      *
123      * @return the new <code>KeyGenerator</code> object
124      *
125      * @exception NullPointerException if the specified algorithm is null.
126      * @exception NoSuchAlgorithmException if a key generator for the
127      * specified algorithm is not available in the default provider
128      * package or any of the other provider packages that were searched.
129      */
130     public static final KeyGenerator getInstance(String algorithm)
131         throws NoSuchAlgorithmException
132     { }
133 
134     /** 
135      * Generates a <code>KeyGenerator</code> object for the specified key
136      * algorithm from the specified provider.
137      *
138      * @param algorithm the standard name of the requested key 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 name of the provider
144      *
145      * @return the new <code>KeyGenerator</code> object
146      *
147      * @exception NullPointerException if the specified algorithm is null.
148      * @exception NoSuchAlgorithmException if a key generator for the
149      * specified algorithm is not available from the specified provider.
150      * @exception NoSuchProviderException if the specified provider has not
151      * been configured.
152      * @exception IllegalArgumentException if the <code>provider</code>
153      * is null.
154      */
155     public static final KeyGenerator getInstance(String algorithm, String
156         provider) throws NoSuchAlgorithmException, NoSuchProviderException
157     { }
158 
159     /** 
160      * Generates a <code>KeyGenerator</code> object for the specified key
161      * algorithm from the specified provider. Note: the <code>provider</code>
162      * doesn't have to be registered.
163      *
164      * @param algorithm the standard name of the requested key algorithm.
165      * See Appendix A in the
166      * <a HREF="../../../guide/security/jce/JCERefGuide.html#AppA">
167      * Java Cryptography Extension Reference Guide</a> 
168      * for information about standard algorithm names.
169      * @param provider the provider
170      *
171      * @return the new <code>KeyGenerator</code> object
172      *
173      * @exception NullPointerException if the specified algorithm is null.
174      * @exception NoSuchAlgorithmException if a key generator for the
175      * specified algorithm is not available from the specified provider.
176      * @exception IllegalArgumentException if the <code>provider</code>
177      * is null.
178      */
179     public static final KeyGenerator getInstance(String algorithm, Provider
180         provider) throws NoSuchAlgorithmException
181     { }
182 
183     /** 
184      * Returns the provider of this <code>KeyGenerator</code> object.
185      * 
186      * @return the provider of this <code>KeyGenerator</code> object
187      */
188     public final Provider getProvider() { }
189 
190     /** 
191      * Initializes this key generator.
192      * 
193      * @param random the source of randomness for this generator
194      */
195     public final void init(SecureRandom random) { }
196 
197     /** 
198      * Initializes this key generator with the specified parameter set.
199      *
200      * <p> If this key generator requires any random bytes, it will get them
201      * using the
202      * {@link SecureRandom <code>SecureRandom</code>}
203      * implementation of the highest-priority installed
204      * provider as the source of randomness.
205      * (If none of the installed providers supply an implementation of
206      * SecureRandom, a system-provided source of randomness will be used.)
207      *
208      * @param params the key generation parameters
209      *
210      * @exception InvalidAlgorithmParameterException if the given parameters
211      * are inappropriate for this key generator
212      */
213     public final void init(AlgorithmParameterSpec params)
214         throws InvalidAlgorithmParameterException
215     { }
216 
217     /** 
218      * Initializes this key generator with the specified parameter
219      * set and a user-provided source of randomness.
220      *
221      * @param params the key generation parameters
222      * @param random the source of randomness for this key generator
223      *
224      * @exception InvalidAlgorithmParameterException if <code>params</code> is
225      * inappropriate for this key generator
226      */
227     public final void init(AlgorithmParameterSpec params, SecureRandom random)
228         throws InvalidAlgorithmParameterException
229     { }
230 
231     /** 
232      * Initializes this key generator for a certain keysize.
233      *
234      * <p> If this key generator requires any random bytes, it will get them
235      * using the
236      * {@link SecureRandom <code>SecureRandom</code>}
237      * implementation of the highest-priority installed
238      * provider as the source of randomness.
239      * (If none of the installed providers supply an implementation of
240      * SecureRandom, a system-provided source of randomness will be used.)
241      *
242      * @param keysize the keysize. This is an algorithm-specific metric,
243      * specified in number of bits.
244      *
245      * @exception InvalidParameterException if the keysize is wrong or not
246      * supported.
247      */
248     public final void init(int keysize) { }
249 
250     /** 
251      * Initializes this key generator for a certain keysize, using a
252      * user-provided source of randomness.
253      *
254      * @param keysize the keysize. This is an algorithm-specific metric,
255      * specified in number of bits.
256      * @param random the source of randomness for this key generator
257      *
258      * @exception InvalidParameterException if the keysize is wrong or not
259      * supported.
260      */
261     public final void init(int keysize, SecureRandom random) { }
262 
263     /** 
264      * Generates a secret key.
265      *
266      * @return the new key
267      */
268     public final SecretKey generateKey() { }
269 }
270
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Java Books Remove Frame
Popular Tags