1 /*
2 * Copyright (c) 1997, 2016, 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} 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} 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.
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} 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} algorithms and
71 * keysizes in parentheses:
72 * <ul>
73 * <li>{@code DiffieHellman} (1024, 2048, 4096)</li>
74 * <li>{@code DSA} (1024, 2048)</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 * @implNote
142 * The JDK Reference Implementation additionally uses the
143 * {@code jdk.security.provider.preferred}
144 * {@link Security#getProperty(String) Security} property to determine
145 * the preferred provider order for the specified algorithm. This
146 * may be different than the order of providers returned by
147 * {@link Security#getProviders() Security.getProviders()}.
148 *
149 * @param algorithm the name of the algorithm this
150 * parameter generator is associated with.
151 * See the AlgorithmParameterGenerator section in the <a href=
152 * "{@docRoot}/../technotes/guides/security/StandardNames.html#AlgorithmParameterGenerator">
153 * Java Cryptography Architecture Standard Algorithm Name Documentation</a>
154 * for information about standard algorithm names.
155 *
156 * @return the new AlgorithmParameterGenerator object.
157 *
158 * @exception NoSuchAlgorithmException if no Provider supports an
159 * AlgorithmParameterGeneratorSpi implementation for the
160 * specified algorithm.
161 *
162 * @see Provider
163 */
164 public static AlgorithmParameterGenerator getInstance(String algorithm)
165 throws NoSuchAlgorithmException {
166 try {
167 Object[] objs = Security.getImpl(algorithm,
168 "AlgorithmParameterGenerator",
169 (String)null);
170 return new AlgorithmParameterGenerator
171 ((AlgorithmParameterGeneratorSpi)objs[0],
172 (Provider)objs[1],
173 algorithm);
174 } catch(NoSuchProviderException e) {
175 throw new NoSuchAlgorithmException(algorithm + " not found");
176 }
177 }
178
179 /**
180 * Returns an AlgorithmParameterGenerator object for generating
181 * a set of parameters to be used with the specified algorithm.
182 *
183 * <p> A new AlgorithmParameterGenerator object encapsulating the
184 * AlgorithmParameterGeneratorSpi implementation from the specified provider
185 * is returned. The specified provider must be registered
186 * in the security provider list.
187 *
188 * <p> Note that the list of registered providers may be retrieved via
189 * the {@link Security#getProviders() Security.getProviders()} method.
190 *
191 * @param algorithm the name of the algorithm this
192 * parameter generator is associated with.
193 * See the AlgorithmParameterGenerator section in the <a href=
194 * "{@docRoot}/../technotes/guides/security/StandardNames.html#AlgorithmParameterGenerator">
195 * Java Cryptography Architecture Standard Algorithm Name Documentation</a>
196 * for information about standard algorithm names.
197 *
198 * @param provider the string name of the Provider.
199 *
200 * @return the new AlgorithmParameterGenerator object.
201 *
202 * @exception NoSuchAlgorithmException if an AlgorithmParameterGeneratorSpi
203 * implementation for the specified algorithm is not
204 * available from the specified provider.
205 *
206 * @exception NoSuchProviderException if the specified provider is not
207 * registered in the security provider list.
208 *
209 * @exception IllegalArgumentException if the provider name is null
210 * or empty.
211 *
212 * @see Provider
213 */
214 public static AlgorithmParameterGenerator getInstance(String algorithm,
215 String provider)
216 throws NoSuchAlgorithmException, NoSuchProviderException
217 {
218 if (provider == null || provider.length() == 0)
219 throw new IllegalArgumentException("missing provider");
220 Object[] objs = Security.getImpl(algorithm,
221 "AlgorithmParameterGenerator",
222 provider);
223 return new AlgorithmParameterGenerator
224 ((AlgorithmParameterGeneratorSpi)objs[0], (Provider)objs[1],
225 algorithm);
226 }
227
228 /**
229 * Returns an AlgorithmParameterGenerator object for generating
230 * a set of parameters to be used with the specified algorithm.
231 *
232 * <p> A new AlgorithmParameterGenerator object encapsulating the
233 * AlgorithmParameterGeneratorSpi implementation from the specified Provider
234 * object is returned. Note that the specified Provider object
235 * does not have to be registered in the provider list.
236 *
237 * @param algorithm the string name of the algorithm this
238 * parameter generator is associated with.
239 * See the AlgorithmParameterGenerator section in the <a href=
240 * "{@docRoot}/../technotes/guides/security/StandardNames.html#AlgorithmParameterGenerator">
241 * Java Cryptography Architecture Standard Algorithm Name Documentation</a>
242 * for information about standard algorithm names.
243 *
244 * @param provider the Provider object.
245 *
246 * @return the new AlgorithmParameterGenerator object.
247 *
248 * @exception NoSuchAlgorithmException if an AlgorithmParameterGeneratorSpi
249 * implementation for the specified algorithm is not available
250 * from the specified Provider object.
251 *
252 * @exception IllegalArgumentException if the specified provider is null.
253 *
254 * @see Provider
255 *
256 * @since 1.4
257 */
258 public static AlgorithmParameterGenerator getInstance(String algorithm,
259 Provider provider)
260 throws NoSuchAlgorithmException
261 {
262 if (provider == null)
263 throw new IllegalArgumentException("missing provider");
264 Object[] objs = Security.getImpl(algorithm,
265 "AlgorithmParameterGenerator",
266 provider);
267 return new AlgorithmParameterGenerator
268 ((AlgorithmParameterGeneratorSpi)objs[0], (Provider)objs[1],
269 algorithm);
270 }
271
272 /**
273 * Returns the provider of this algorithm parameter generator object.
274 *
275 * @return the provider of this algorithm parameter generator object
276 */
277 public final Provider getProvider() {
278 return this.provider;
279 }
280
281 /**
282 * Initializes this parameter generator for a certain size.
283 * To create the parameters, the {@code SecureRandom}
284 * implementation of the highest-priority installed provider is used as
285 * the source of randomness.
286 * (If none of the installed providers supply an implementation of
287 * {@code SecureRandom}, a system-provided source of randomness is
288 * used.)
289 *
290 * @param size the size (number of bits).
291 */
292 public final void init(int size) {
293 paramGenSpi.engineInit(size, new SecureRandom());
294 }
295
296 /**
297 * Initializes this parameter generator for a certain size and source
298 * of randomness.
299 *
300 * @param size the size (number of bits).
301 * @param random the source of randomness.
302 */
303 public final void init(int size, SecureRandom random) {
304 paramGenSpi.engineInit(size, random);
305 }
306
307 /**
308 * Initializes this parameter generator with a set of algorithm-specific
309 * parameter generation values.
310 * To generate the parameters, the {@code SecureRandom}
311 * implementation of the highest-priority installed provider is used as
312 * the source of randomness.
313 * (If none of the installed providers supply an implementation of
314 * {@code SecureRandom}, a system-provided source of randomness is
315 * used.)
316 *
317 * @param genParamSpec the set of algorithm-specific parameter generation values.
318 *
319 * @exception InvalidAlgorithmParameterException if the given parameter
320 * generation values are inappropriate for this parameter generator.
321 */
322 public final void init(AlgorithmParameterSpec genParamSpec)
323 throws InvalidAlgorithmParameterException {
324 paramGenSpi.engineInit(genParamSpec, new SecureRandom());
325 }
326
327 /**
328 * Initializes this parameter generator with a set of algorithm-specific
329 * parameter generation values.
330 *
331 * @param genParamSpec the set of algorithm-specific parameter generation values.
332 * @param random the source of randomness.
333 *
334 * @exception InvalidAlgorithmParameterException if the given parameter
335 * generation values are inappropriate for this parameter generator.
336 */
337 public final void init(AlgorithmParameterSpec genParamSpec,
338 SecureRandom random)
339 throws InvalidAlgorithmParameterException {
340 paramGenSpi.engineInit(genParamSpec, random);
341 }
342
343 /**
344 * Generates the parameters.
345 *
346 * @return the new AlgorithmParameters object.
347 */
348 public final AlgorithmParameters generateParameters() {
349 return paramGenSpi.engineGenerateParameters();
350 }
351 }