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 import java.util.Objects;
30
31 /**
32 * The {@code AlgorithmParameterGenerator} class is used to generate a
33 * set of
34 * parameters to be used with a certain algorithm. Parameter generators
35 * are constructed using the {@code getInstance} factory methods
36 * (static methods that return instances of a given class).
37 *
38 * <P>The object that will generate the parameters can be initialized
39 * in two different ways: in an algorithm-independent manner, or in an
40 * algorithm-specific manner:
41 *
42 * <ul>
43 * <li>The algorithm-independent approach uses the fact that all parameter
44 * generators share the concept of a "size" and a
45 * source of randomness. The measure of size is universally shared
46 * by all algorithm parameters, though it is interpreted differently
47 * for different algorithms. For example, in the case of parameters for
48 * the <i>DSA</i> algorithm, "size" corresponds to the size
49 * of the prime modulus (in bits).
50 * When using this approach, algorithm-specific parameter generation
51 * values - if any - default to some standard values, unless they can be
52 * derived from the specified size.
53 *
54 * <li>The other approach initializes a parameter generator object
55 * using algorithm-specific semantics, which are represented by a set of
56 * algorithm-specific parameter generation values. To generate
57 * Diffie-Hellman system parameters, for example, the parameter generation
58 * values usually
59 * consist of the size of the prime modulus and the size of the
60 * random exponent, both specified in number of bits.
61 * </ul>
62 *
63 * <P>In case the client does not explicitly initialize the
64 * AlgorithmParameterGenerator
65 * (via a call to an {@code init} method), each provider must supply (and
66 * document) a default initialization. For example, the Sun provider uses a
67 * default modulus prime size of 1024 bits for the generation of DSA
68 * parameters.
69 *
70 * <p> Every implementation of the Java platform is required to support the
71 * following standard {@code AlgorithmParameterGenerator} algorithms and
72 * keysizes in parentheses:
73 * <ul>
74 * <li>{@code DiffieHellman} (1024, 2048, 4096)</li>
75 * <li>{@code DSA} (1024, 2048)</li>
76 * </ul>
77 * These algorithms are described in the <a href=
78 * "{@docRoot}/../technotes/guides/security/StandardNames.html#AlgorithmParameterGenerator">
79 * AlgorithmParameterGenerator section</a> of the
80 * Java Cryptography Architecture Standard Algorithm Name Documentation.
81 * Consult the release documentation for your implementation to see if any
82 * other algorithms are supported.
83 *
84 * @author Jan Luehe
85 *
86 *
87 * @see AlgorithmParameters
88 * @see java.security.spec.AlgorithmParameterSpec
89 *
90 * @since 1.2
91 */
92
93 public class AlgorithmParameterGenerator {
94
95 // The provider
96 private Provider provider;
97
98 // The provider implementation (delegate)
99 private AlgorithmParameterGeneratorSpi paramGenSpi;
100
101 // The algorithm
102 private String algorithm;
103
104 /**
105 * Creates an AlgorithmParameterGenerator object.
106 *
107 * @param paramGenSpi the delegate
108 * @param provider the provider
109 * @param algorithm the algorithm
110 */
111 protected AlgorithmParameterGenerator
112 (AlgorithmParameterGeneratorSpi paramGenSpi, Provider provider,
113 String algorithm) {
114 this.paramGenSpi = paramGenSpi;
115 this.provider = provider;
116 this.algorithm = algorithm;
117 }
118
119 /**
120 * Returns the standard name of the algorithm this parameter
121 * generator is associated with.
122 *
123 * @return the string name of the algorithm.
124 */
125 public final String getAlgorithm() {
126 return this.algorithm;
127 }
128
129 /**
130 * Returns an AlgorithmParameterGenerator object for generating
131 * a set of parameters to be used with the specified algorithm.
132 *
133 * <p> This method traverses the list of registered security Providers,
134 * starting with the most preferred Provider.
135 * A new AlgorithmParameterGenerator object encapsulating the
136 * AlgorithmParameterGeneratorSpi implementation from the first
137 * Provider that supports the specified algorithm is returned.
138 *
139 * <p> Note that the list of registered providers may be retrieved via
140 * the {@link Security#getProviders() Security.getProviders()} method.
141 *
142 * @implNote
143 * The JDK Reference Implementation additionally uses the
144 * {@code jdk.security.provider.preferred}
145 * {@link Security#getProperty(String) Security} property to determine
146 * the preferred provider order for the specified algorithm. This
147 * may be different than the order of providers returned by
148 * {@link Security#getProviders() Security.getProviders()}.
149 *
150 * @param algorithm the name of the algorithm this
151 * parameter generator is associated with.
152 * See the AlgorithmParameterGenerator section in the <a href=
153 * "{@docRoot}/../technotes/guides/security/StandardNames.html#AlgorithmParameterGenerator">
154 * Java Cryptography Architecture Standard Algorithm Name Documentation</a>
155 * for information about standard algorithm names.
156 *
157 * @return the new {@code AlgorithmParameterGenerator} object
158 *
159 * @throws NoSuchAlgorithmException if no {@code Provider} supports an
160 * {@code AlgorithmParameterGeneratorSpi} implementation for the
161 * specified algorithm
162 *
163 * @throws NullPointerException if {@code algorithm} is {@code null}
164 *
165 * @see Provider
166 */
167 public static AlgorithmParameterGenerator getInstance(String algorithm)
168 throws NoSuchAlgorithmException {
169 Objects.requireNonNull(algorithm, "null algorithm name");
170 try {
171 Object[] objs = Security.getImpl(algorithm,
172 "AlgorithmParameterGenerator",
173 (String)null);
174 return new AlgorithmParameterGenerator
175 ((AlgorithmParameterGeneratorSpi)objs[0],
176 (Provider)objs[1],
177 algorithm);
178 } catch(NoSuchProviderException e) {
179 throw new NoSuchAlgorithmException(algorithm + " not found");
180 }
181 }
182
183 /**
184 * Returns an AlgorithmParameterGenerator object for generating
185 * a set of parameters to be used with the specified algorithm.
186 *
187 * <p> A new AlgorithmParameterGenerator object encapsulating the
188 * AlgorithmParameterGeneratorSpi implementation from the specified provider
189 * is returned. The specified provider must be registered
190 * in the security provider list.
191 *
192 * <p> Note that the list of registered providers may be retrieved via
193 * the {@link Security#getProviders() Security.getProviders()} method.
194 *
195 * @param algorithm the name of the algorithm this
196 * parameter generator is associated with.
197 * See the AlgorithmParameterGenerator section in the <a href=
198 * "{@docRoot}/../technotes/guides/security/StandardNames.html#AlgorithmParameterGenerator">
199 * Java Cryptography Architecture Standard Algorithm Name Documentation</a>
200 * for information about standard algorithm names.
201 *
202 * @param provider the string name of the Provider.
203 *
204 * @return the new {@code AlgorithmParameterGenerator} object
205 *
206 * @throws IllegalArgumentException if the provider name is {@code null}
207 * or empty
208 *
209 * @throws NoSuchAlgorithmException if an
210 * {@code AlgorithmParameterGeneratorSpi}
211 * implementation for the specified algorithm is not
212 * available from the specified provider
213 *
214 * @throws NoSuchProviderException if the specified provider is not
215 * registered in the security provider list
216 *
217 * @throws NullPointerException if {@code algorithm} is {@code null}
218 *
219 * @see Provider
220 */
221 public static AlgorithmParameterGenerator getInstance(String algorithm,
222 String provider)
223 throws NoSuchAlgorithmException, NoSuchProviderException
224 {
225 Objects.requireNonNull(algorithm, "null algorithm name");
226 if (provider == null || provider.length() == 0)
227 throw new IllegalArgumentException("missing provider");
228 Object[] objs = Security.getImpl(algorithm,
229 "AlgorithmParameterGenerator",
230 provider);
231 return new AlgorithmParameterGenerator
232 ((AlgorithmParameterGeneratorSpi)objs[0], (Provider)objs[1],
233 algorithm);
234 }
235
236 /**
237 * Returns an AlgorithmParameterGenerator object for generating
238 * a set of parameters to be used with the specified algorithm.
239 *
240 * <p> A new AlgorithmParameterGenerator object encapsulating the
241 * AlgorithmParameterGeneratorSpi implementation from the specified Provider
242 * object is returned. Note that the specified Provider object
243 * does not have to be registered in the provider list.
244 *
245 * @param algorithm the string name of the algorithm this
246 * parameter generator is associated with.
247 * See the AlgorithmParameterGenerator section in the <a href=
248 * "{@docRoot}/../technotes/guides/security/StandardNames.html#AlgorithmParameterGenerator">
249 * Java Cryptography Architecture Standard Algorithm Name Documentation</a>
250 * for information about standard algorithm names.
251 *
252 * @param provider the {@code Provider} object.
253 *
254 * @return the new {@code AlgorithmParameterGenerator} object
255 *
256 * @throws IllegalArgumentException if the specified provider is
257 * {@code null}
258 *
259 * @throws NoSuchAlgorithmException if an
260 * {@code AlgorithmParameterGeneratorSpi}
261 * implementation for the specified algorithm is not available
262 * from the specified {@code Provider} object
263 *
264 * @throws NullPointerException if {@code algorithm} is {@code null}
265 *
266 * @see Provider
267 *
268 * @since 1.4
269 */
270 public static AlgorithmParameterGenerator getInstance(String algorithm,
271 Provider provider)
272 throws NoSuchAlgorithmException
273 {
274 Objects.requireNonNull(algorithm, "null algorithm name");
275 if (provider == null)
276 throw new IllegalArgumentException("missing provider");
277 Object[] objs = Security.getImpl(algorithm,
278 "AlgorithmParameterGenerator",
279 provider);
280 return new AlgorithmParameterGenerator
281 ((AlgorithmParameterGeneratorSpi)objs[0], (Provider)objs[1],
282 algorithm);
283 }
284
285 /**
286 * Returns the provider of this algorithm parameter generator object.
287 *
288 * @return the provider of this algorithm parameter generator object
289 */
290 public final Provider getProvider() {
291 return this.provider;
292 }
293
294 /**
295 * Initializes this parameter generator for a certain size.
296 * To create the parameters, the {@code SecureRandom}
297 * implementation of the highest-priority installed provider is used as
298 * the source of randomness.
299 * (If none of the installed providers supply an implementation of
300 * {@code SecureRandom}, a system-provided source of randomness is
301 * used.)
302 *
303 * @param size the size (number of bits).
304 */
305 public final void init(int size) {
306 paramGenSpi.engineInit(size, new SecureRandom());
307 }
308
309 /**
310 * Initializes this parameter generator for a certain size and source
311 * of randomness.
312 *
313 * @param size the size (number of bits).
314 * @param random the source of randomness.
315 */
316 public final void init(int size, SecureRandom random) {
317 paramGenSpi.engineInit(size, random);
318 }
319
320 /**
321 * Initializes this parameter generator with a set of algorithm-specific
322 * parameter generation values.
323 * To generate the parameters, the {@code SecureRandom}
324 * implementation of the highest-priority installed provider is used as
325 * the source of randomness.
326 * (If none of the installed providers supply an implementation of
327 * {@code SecureRandom}, a system-provided source of randomness is
328 * used.)
329 *
330 * @param genParamSpec the set of algorithm-specific parameter generation values.
331 *
332 * @exception InvalidAlgorithmParameterException if the given parameter
333 * generation values are inappropriate for this parameter generator.
334 */
335 public final void init(AlgorithmParameterSpec genParamSpec)
336 throws InvalidAlgorithmParameterException {
337 paramGenSpi.engineInit(genParamSpec, new SecureRandom());
338 }
339
340 /**
341 * Initializes this parameter generator with a set of algorithm-specific
342 * parameter generation values.
343 *
344 * @param genParamSpec the set of algorithm-specific parameter generation values.
345 * @param random the source of randomness.
346 *
347 * @exception InvalidAlgorithmParameterException if the given parameter
348 * generation values are inappropriate for this parameter generator.
349 */
350 public final void init(AlgorithmParameterSpec genParamSpec,
351 SecureRandom random)
352 throws InvalidAlgorithmParameterException {
353 paramGenSpi.engineInit(genParamSpec, random);
354 }
355
356 /**
357 * Generates the parameters.
358 *
359 * @return the new AlgorithmParameters object.
360 */
361 public final AlgorithmParameters generateParameters() {
362 return paramGenSpi.engineGenerateParameters();
363 }
364 }