1 /*
2 * Copyright (c) 1997, 2011, Oracle and/or its affiliates. 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. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * 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 * <p> Every implementation of the Java platform is required to support the
70 * following standard <code>AlgorithmParameterGenerator</code> algorithms and
71 * keysizes in parentheses:
72 * <ul>
73 * <li><tt>DiffieHellman</tt> (1024)</li>
74 * <li><tt>DSA</tt> (1024)</li>
75 * </ul>
76 * These algorithms are described in the <a href=
77 * "{@docRoot}/../technotes/guides/security/StandardNames.html#AlgorithmParameterGenerator">
78 * AlgorithmParameterGenerator section</a> of the
79 * Java Cryptography Architecture Standard Algorithm Name Documentation.
80 * Consult the release documentation for your implementation to see if any
81 * other algorithms are supported.
82 *
83 * @author Jan Luehe
84 *
85 *
86 * @see AlgorithmParameters
87 * @see java.security.spec.AlgorithmParameterSpec
88 *
89 * @since 1.2
90 */
91
92 public class AlgorithmParameterGenerator {
93
94 // The provider
95 private Provider provider;
96
97 // The provider implementation (delegate)
98 private AlgorithmParameterGeneratorSpi paramGenSpi;
99
100 // The algorithm
101 private String algorithm;
102
103 /**
104 * Creates an AlgorithmParameterGenerator object.
105 *
106 * @param paramGenSpi the delegate
107 * @param provider the provider
108 * @param algorithm the algorithm
109 */
110 protected AlgorithmParameterGenerator
111 (AlgorithmParameterGeneratorSpi paramGenSpi, Provider provider,
112 String algorithm) {
113 this.paramGenSpi = paramGenSpi;
114 this.provider = provider;
115 this.algorithm = algorithm;
116 }
117
118 /**
119 * Returns the standard name of the algorithm this parameter
120 * generator is associated with.
121 *
122 * @return the string name of the algorithm.
123 */
124 public final String getAlgorithm() {
125 return this.algorithm;
126 }
127
128 /**
129 * Returns an AlgorithmParameterGenerator object for generating
130 * a set of parameters to be used with the specified algorithm.
131 *
132 * <p> This method traverses the list of registered security Providers,
133 * starting with the most preferred Provider.
134 * A new AlgorithmParameterGenerator object encapsulating the
135 * AlgorithmParameterGeneratorSpi implementation from the first
136 * Provider that supports the specified algorithm is returned.
137 *
138 * <p> Note that the list of registered providers may be retrieved via
139 * the {@link Security#getProviders() Security.getProviders()} method.
140 *
141 * @param algorithm the name of the algorithm this
142 * parameter generator is associated with.
143 * See the AlgorithmParameterGenerator section in the <a href=
144 * "{@docRoot}/../technotes/guides/security/StandardNames.html#AlgorithmParameterGenerator">
145 * Java Cryptography Architecture Standard Algorithm Name Documentation</a>
146 * for information about standard algorithm names.
147 *
148 * @return the new AlgorithmParameterGenerator object.
149 *
150 * @exception NoSuchAlgorithmException if no Provider supports an
151 * AlgorithmParameterGeneratorSpi implementation for the
152 * specified algorithm.
153 *
154 * @see Provider
155 */
156 public static AlgorithmParameterGenerator getInstance(String algorithm)
157 throws NoSuchAlgorithmException {
158 try {
159 Object[] objs = Security.getImpl(algorithm,
160 "AlgorithmParameterGenerator",
161 (String)null);
162 return new AlgorithmParameterGenerator
163 ((AlgorithmParameterGeneratorSpi)objs[0],
164 (Provider)objs[1],
165 algorithm);
166 } catch(NoSuchProviderException e) {
167 throw new NoSuchAlgorithmException(algorithm + " not found");
168 }
169 }
170
171 /**
172 * Returns an AlgorithmParameterGenerator object for generating
173 * a set of parameters to be used with the specified algorithm.
174 *
175 * <p> A new AlgorithmParameterGenerator object encapsulating the
176 * AlgorithmParameterGeneratorSpi implementation from the specified provider
177 * is returned. The specified provider must be registered
178 * in the security provider list.
179 *
180 * <p> Note that the list of registered providers may be retrieved via
181 * the {@link Security#getProviders() Security.getProviders()} method.
182 *
183 * @param algorithm the name of the algorithm this
184 * parameter generator is associated with.
185 * See the AlgorithmParameterGenerator section in the <a href=
186 * "{@docRoot}/../technotes/guides/security/StandardNames.html#AlgorithmParameterGenerator">
187 * Java Cryptography Architecture Standard Algorithm Name Documentation</a>
188 * for information about standard algorithm names.
189 *
190 * @param provider the string name of the Provider.
191 *
192 * @return the new AlgorithmParameterGenerator object.
193 *
194 * @exception NoSuchAlgorithmException if an AlgorithmParameterGeneratorSpi
195 * implementation for the specified algorithm is not
196 * available from the specified provider.
197 *
198 * @exception NoSuchProviderException if the specified provider is not
199 * registered in the security provider list.
200 *
201 * @exception IllegalArgumentException if the provider name is null
202 * or empty.
203 *
204 * @see Provider
205 */
206 public static AlgorithmParameterGenerator getInstance(String algorithm,
207 String provider)
208 throws NoSuchAlgorithmException, NoSuchProviderException
209 {
210 if (provider == null || provider.length() == 0)
211 throw new IllegalArgumentException("missing provider");
212 Object[] objs = Security.getImpl(algorithm,
213 "AlgorithmParameterGenerator",
214 provider);
215 return new AlgorithmParameterGenerator
216 ((AlgorithmParameterGeneratorSpi)objs[0], (Provider)objs[1],
217 algorithm);
218 }
219
220 /**
221 * Returns an AlgorithmParameterGenerator object for generating
222 * a set of parameters to be used with the specified algorithm.
223 *
224 * <p> A new AlgorithmParameterGenerator object encapsulating the
225 * AlgorithmParameterGeneratorSpi implementation from the specified Provider
226 * object is returned. Note that the specified Provider object
227 * does not have to be registered in the provider list.
228 *
229 * @param algorithm the string name of the algorithm this
230 * parameter generator is associated with.
231 * See the AlgorithmParameterGenerator section in the <a href=
232 * "{@docRoot}/../technotes/guides/security/StandardNames.html#AlgorithmParameterGenerator">
233 * Java Cryptography Architecture Standard Algorithm Name Documentation</a>
234 * for information about standard algorithm names.
235 *
236 * @param provider the Provider object.
237 *
238 * @return the new AlgorithmParameterGenerator object.
239 *
240 * @exception NoSuchAlgorithmException if an AlgorithmParameterGeneratorSpi
241 * implementation for the specified algorithm is not available
242 * from the specified Provider object.
243 *
244 * @exception IllegalArgumentException if the specified provider is null.
245 *
246 * @see Provider
247 *
248 * @since 1.4
249 */
250 public static AlgorithmParameterGenerator getInstance(String algorithm,
251 Provider provider)
252 throws NoSuchAlgorithmException
253 {
254 if (provider == null)
255 throw new IllegalArgumentException("missing provider");
256 Object[] objs = Security.getImpl(algorithm,
257 "AlgorithmParameterGenerator",
258 provider);
259 return new AlgorithmParameterGenerator
260 ((AlgorithmParameterGeneratorSpi)objs[0], (Provider)objs[1],
261 algorithm);
262 }
263
264 /**
265 * Returns the provider of this algorithm parameter generator object.
266 *
267 * @return the provider of this algorithm parameter generator object
268 */
269 public final Provider getProvider() {
270 return this.provider;
271 }
272
273 /**
274 * Initializes this parameter generator for a certain size.
275 * To create the parameters, the <code>SecureRandom</code>
276 * implementation of the highest-priority installed provider is used as
277 * the source of randomness.
278 * (If none of the installed providers supply an implementation of
279 * <code>SecureRandom</code>, a system-provided source of randomness is
280 * used.)
281 *
282 * @param size the size (number of bits).
283 */
284 public final void init(int size) {
285 paramGenSpi.engineInit(size, new SecureRandom());
286 }
287
288 /**
289 * Initializes this parameter generator for a certain size and source
290 * of randomness.
291 *
292 * @param size the size (number of bits).
293 * @param random the source of randomness.
294 */
295 public final void init(int size, SecureRandom random) {
296 paramGenSpi.engineInit(size, random);
297 }
298
299 /**
300 * Initializes this parameter generator with a set of algorithm-specific
301 * parameter generation values.
302 * To generate the parameters, the <code>SecureRandom</code>
303 * implementation of the highest-priority installed provider is used as
304 * the source of randomness.
305 * (If none of the installed providers supply an implementation of
306 * <code>SecureRandom</code>, a system-provided source of randomness is
307 * used.)
308 *
309 * @param genParamSpec the set of algorithm-specific parameter generation values.
310 *
311 * @exception InvalidAlgorithmParameterException if the given parameter
312 * generation values are inappropriate for this parameter generator.
313 */
314 public final void init(AlgorithmParameterSpec genParamSpec)
315 throws InvalidAlgorithmParameterException {
316 paramGenSpi.engineInit(genParamSpec, new SecureRandom());
317 }
318
319 /**
320 * Initializes this parameter generator with a set of algorithm-specific
321 * parameter generation values.
322 *
323 * @param genParamSpec the set of algorithm-specific parameter generation values.
324 * @param random the source of randomness.
325 *
326 * @exception InvalidAlgorithmParameterException if the given parameter
327 * generation values are inappropriate for this parameter generator.
328 */
329 public final void init(AlgorithmParameterSpec genParamSpec,
330 SecureRandom random)
331 throws InvalidAlgorithmParameterException {
332 paramGenSpi.engineInit(genParamSpec, random);
333 }
334
335 /**
336 * Generates the parameters.
337 *
338 * @return the new AlgorithmParameters object.
339 */
340 public final AlgorithmParameters generateParameters() {
341 return paramGenSpi.engineGenerateParameters();
342 }
343 }