1 /*
2 * Copyright 1997-2006 Sun Microsystems, Inc. All Rights Reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26 package java.security;
27
28 import java.security.spec.AlgorithmParameterSpec;
29
30 /**
31 * The <code>AlgorithmParameterGenerator</code> class is used to generate a
32 * set of
33 * parameters to be used with a certain algorithm. Parameter generators
34 * are constructed using the <code>getInstance</code> factory methods
35 * (static methods that return instances of a given class).
36 *
37 * <P>The object that will generate the parameters can be initialized
38 * in two different ways: in an algorithm-independent manner, or in an
39 * algorithm-specific manner:
40 *
41 * <ul>
42 * <li>The algorithm-independent approach uses the fact that all parameter
43 * generators share the concept of a "size" and a
44 * source of randomness. The measure of size is universally shared
45 * by all algorithm parameters, though it is interpreted differently
46 * for different algorithms. For example, in the case of parameters for
47 * the <i>DSA</i> algorithm, "size" corresponds to the size
48 * of the prime modulus (in bits).
49 * When using this approach, algorithm-specific parameter generation
50 * values - if any - default to some standard values, unless they can be
51 * derived from the specified size.<P>
52 *
53 * <li>The other approach initializes a parameter generator object
54 * using algorithm-specific semantics, which are represented by a set of
55 * algorithm-specific parameter generation values. To generate
56 * Diffie-Hellman system parameters, for example, the parameter generation
57 * values usually
58 * consist of the size of the prime modulus and the size of the
59 * random exponent, both specified in number of bits.
60 * </ul>
61 *
62 * <P>In case the client does not explicitly initialize the
63 * AlgorithmParameterGenerator
64 * (via a call to an <code>init</code> method), each provider must supply (and
65 * document) a default initialization. For example, the Sun provider uses a
66 * default modulus prime size of 1024 bits for the generation of DSA
67 * parameters.
68 *
69 * @author Jan Luehe
70 *
71 *
72 * @see AlgorithmParameters
73 * @see java.security.spec.AlgorithmParameterSpec
74 *
75 * @since 1.2
76 */
77
78 public class AlgorithmParameterGenerator {
79
80 // The provider
81 private Provider provider;
82
83 // The provider implementation (delegate)
84 private AlgorithmParameterGeneratorSpi paramGenSpi;
85
86 // The algorithm
87 private String algorithm;
88
89 /**
90 * Creates an AlgorithmParameterGenerator object.
91 *
92 * @param paramGenSpi the delegate
93 * @param provider the provider
94 * @param algorithm the algorithm
95 */
96 protected AlgorithmParameterGenerator
97 (AlgorithmParameterGeneratorSpi paramGenSpi, Provider provider,
98 String algorithm) {
99 this.paramGenSpi = paramGenSpi;
100 this.provider = provider;
101 this.algorithm = algorithm;
102 }
103
104 /**
105 * Returns the standard name of the algorithm this parameter
106 * generator is associated with.
107 *
108 * @return the string name of the algorithm.
109 */
110 public final String getAlgorithm() {
111 return this.algorithm;
112 }
113
114 /**
115 * Returns an AlgorithmParameterGenerator object for generating
116 * a set of parameters to be used with the specified algorithm.
117 *
118 * <p> This method traverses the list of registered security Providers,
119 * starting with the most preferred Provider.
120 * A new AlgorithmParameterGenerator object encapsulating the
121 * AlgorithmParameterGeneratorSpi implementation from the first
122 * Provider that supports the specified algorithm is returned.
123 *
124 * <p> Note that the list of registered providers may be retrieved via
125 * the {@link Security#getProviders() Security.getProviders()} method.
126 *
127 * @param algorithm the name of the algorithm this
128 * parameter generator is associated with.
129 * See Appendix A in the <a href=
130 * "../../../technotes/guides/security/crypto/CryptoSpec.html#AppA">
131 * Java Cryptography Architecture API Specification & Reference </a>
132 * for information about standard algorithm names.
133 *
134 * @return the new AlgorithmParameterGenerator object.
135 *
136 * @exception NoSuchAlgorithmException if no Provider supports an
137 * AlgorithmParameterGeneratorSpi implementation for the
138 * specified algorithm.
139 *
140 * @see Provider
141 */
142 public static AlgorithmParameterGenerator getInstance(String algorithm)
143 throws NoSuchAlgorithmException {
144 try {
145 Object[] objs = Security.getImpl(algorithm,
146 "AlgorithmParameterGenerator",
147 (String)null);
148 return new AlgorithmParameterGenerator
149 ((AlgorithmParameterGeneratorSpi)objs[0],
150 (Provider)objs[1],
151 algorithm);
152 } catch(NoSuchProviderException e) {
153 throw new NoSuchAlgorithmException(algorithm + " not found");
154 }
155 }
156
157 /**
158 * Returns an AlgorithmParameterGenerator object for generating
159 * a set of parameters to be used with the specified algorithm.
160 *
161 * <p> A new AlgorithmParameterGenerator object encapsulating the
162 * AlgorithmParameterGeneratorSpi implementation from the specified provider
163 * is returned. The specified provider must be registered
164 * in the security provider list.
165 *
166 * <p> Note that the list of registered providers may be retrieved via
167 * the {@link Security#getProviders() Security.getProviders()} method.
168 *
169 * @param algorithm the name of the algorithm this
170 * parameter generator is associated with.
171 * See Appendix A in the <a href=
172 * "../../../technotes/guides/security/crypto/CryptoSpec.html#AppA">
173 * Java Cryptography Architecture API Specification & Reference </a>
174 * for information about standard algorithm names.
175 *
176 * @param provider the string name of the Provider.
177 *
178 * @return the new AlgorithmParameterGenerator object.
179 *
180 * @exception NoSuchAlgorithmException if an AlgorithmParameterGeneratorSpi
181 * implementation for the specified algorithm is not
182 * available from the specified provider.
183 *
184 * @exception NoSuchProviderException if the specified provider is not
185 * registered in the security provider list.
186 *
187 * @exception IllegalArgumentException if the provider name is null
188 * or empty.
189 *
190 * @see Provider
191 */
192 public static AlgorithmParameterGenerator getInstance(String algorithm,
193 String provider)
194 throws NoSuchAlgorithmException, NoSuchProviderException
195 {
196 if (provider == null || provider.length() == 0)
197 throw new IllegalArgumentException("missing provider");
198 Object[] objs = Security.getImpl(algorithm,
199 "AlgorithmParameterGenerator",
200 provider);
201 return new AlgorithmParameterGenerator
202 ((AlgorithmParameterGeneratorSpi)objs[0], (Provider)objs[1],
203 algorithm);
204 }
205
206 /**
207 * Returns an AlgorithmParameterGenerator object for generating
208 * a set of parameters to be used with the specified algorithm.
209 *
210 * <p> A new AlgorithmParameterGenerator object encapsulating the
211 * AlgorithmParameterGeneratorSpi implementation from the specified Provider
212 * object is returned. Note that the specified Provider object
213 * does not have to be registered in the provider list.
214 *
215 * @param algorithm the string name of the algorithm this
216 * parameter generator is associated with.
217 * See Appendix A in the <a href=
218 * "../../../technotes/guides/security/crypto/CryptoSpec.html#AppA">
219 * Java Cryptography Architecture API Specification & Reference </a>
220 * for information about standard algorithm names.
221 *
222 * @param provider the Provider object.
223 *
224 * @return the new AlgorithmParameterGenerator object.
225 *
226 * @exception NoSuchAlgorithmException if an AlgorithmParameterGeneratorSpi
227 * implementation for the specified algorithm is not available
228 * from the specified Provider object.
229 *
230 * @exception IllegalArgumentException if the specified provider is null.
231 *
232 * @see Provider
233 *
234 * @since 1.4
235 */
236 public static AlgorithmParameterGenerator getInstance(String algorithm,
237 Provider provider)
238 throws NoSuchAlgorithmException
239 {
240 if (provider == null)
241 throw new IllegalArgumentException("missing provider");
242 Object[] objs = Security.getImpl(algorithm,
243 "AlgorithmParameterGenerator",
244 provider);
245 return new AlgorithmParameterGenerator
246 ((AlgorithmParameterGeneratorSpi)objs[0], (Provider)objs[1],
247 algorithm);
248 }
249
250 /**
251 * Returns the provider of this algorithm parameter generator object.
252 *
253 * @return the provider of this algorithm parameter generator object
254 */
255 public final Provider getProvider() {
256 return this.provider;
257 }
258
259 /**
260 * Initializes this parameter generator for a certain size.
261 * To create the parameters, the <code>SecureRandom</code>
262 * implementation of the highest-priority installed provider is used as
263 * the source of randomness.
264 * (If none of the installed providers supply an implementation of
265 * <code>SecureRandom</code>, a system-provided source of randomness is
266 * used.)
267 *
268 * @param size the size (number of bits).
269 */
270 public final void init(int size) {
271 paramGenSpi.engineInit(size, new SecureRandom());
272 }
273
274 /**
275 * Initializes this parameter generator for a certain size and source
276 * of randomness.
277 *
278 * @param size the size (number of bits).
279 * @param random the source of randomness.
280 */
281 public final void init(int size, SecureRandom random) {
282 paramGenSpi.engineInit(size, random);
283 }
284
285 /**
286 * Initializes this parameter generator with a set of algorithm-specific
287 * parameter generation values.
288 * To generate the parameters, the <code>SecureRandom</code>
289 * implementation of the highest-priority installed provider is used as
290 * the source of randomness.
291 * (If none of the installed providers supply an implementation of
292 * <code>SecureRandom</code>, a system-provided source of randomness is
293 * used.)
294 *
295 * @param genParamSpec the set of algorithm-specific parameter generation values.
296 *
297 * @exception InvalidAlgorithmParameterException if the given parameter
298 * generation values are inappropriate for this parameter generator.
299 */
300 public final void init(AlgorithmParameterSpec genParamSpec)
301 throws InvalidAlgorithmParameterException {
302 paramGenSpi.engineInit(genParamSpec, new SecureRandom());
303 }
304
305 /**
306 * Initializes this parameter generator with a set of algorithm-specific
307 * parameter generation values.
308 *
309 * @param genParamSpec the set of algorithm-specific parameter generation values.
310 * @param random the source of randomness.
311 *
312 * @exception InvalidAlgorithmParameterException if the given parameter
313 * generation values are inappropriate for this parameter generator.
314 */
315 public final void init(AlgorithmParameterSpec genParamSpec,
316 SecureRandom random)
317 throws InvalidAlgorithmParameterException {
318 paramGenSpi.engineInit(genParamSpec, random);
319 }
320
321 /**
322 * Generates the parameters.
323 *
324 * @return the new AlgorithmParameters object.
325 */
326 public final AlgorithmParameters generateParameters() {
327 return paramGenSpi.engineGenerateParameters();
328 }
329 }
Save This Page