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.io;
29 import java.security.spec.AlgorithmParameterSpec;
30 import java.security.spec.InvalidParameterSpecException;
31
32 /**
33 * This class is used as an opaque representation of cryptographic parameters.
34 *
35 * <p>An <code>AlgorithmParameters</code> object for managing the parameters
36 * for a particular algorithm can be obtained by
37 * calling one of the <code>getInstance</code> factory methods
38 * (static methods that return instances of a given class).
39 *
40 * <p>Once an <code>AlgorithmParameters</code> object is obtained, it must be
41 * initialized via a call to <code>init</code>, using an appropriate parameter
42 * specification or parameter encoding.
43 *
44 * <p>A transparent parameter specification is obtained from an
45 * <code>AlgorithmParameters</code> object via a call to
46 * <code>getParameterSpec</code>, and a byte encoding of the parameters is
47 * obtained via a call to <code>getEncoded</code>.
48 *
49 * @author Jan Luehe
50 *
51 *
52 * @see java.security.spec.AlgorithmParameterSpec
53 * @see java.security.spec.DSAParameterSpec
54 * @see KeyPairGenerator
55 *
56 * @since 1.2
57 */
58
59 public class AlgorithmParameters {
60
61 // The provider
62 private Provider provider;
63
64 // The provider implementation (delegate)
65 private AlgorithmParametersSpi paramSpi;
66
67 // The algorithm
68 private String algorithm;
69
70 // Has this object been initialized?
71 private boolean initialized = false;
72
73 /**
74 * Creates an AlgorithmParameters object.
75 *
76 * @param paramSpi the delegate
77 * @param provider the provider
78 * @param algorithm the algorithm
79 */
80 protected AlgorithmParameters(AlgorithmParametersSpi paramSpi,
81 Provider provider, String algorithm)
82 {
83 this.paramSpi = paramSpi;
84 this.provider = provider;
85 this.algorithm = algorithm;
86 }
87
88 /**
89 * Returns the name of the algorithm associated with this parameter object.
90 *
91 * @return the algorithm name.
92 */
93 public final String getAlgorithm() {
94 return this.algorithm;
95 }
96
97 /**
98 * Returns a parameter object for the specified algorithm.
99 *
100 * <p> This method traverses the list of registered security Providers,
101 * starting with the most preferred Provider.
102 * A new AlgorithmParameters object encapsulating the
103 * AlgorithmParametersSpi implementation from the first
104 * Provider that supports the specified algorithm is returned.
105 *
106 * <p> Note that the list of registered providers may be retrieved via
107 * the {@link Security#getProviders() Security.getProviders()} method.
108 *
109 * <p> The returned parameter object must be initialized via a call to
110 * <code>init</code>, using an appropriate parameter specification or
111 * parameter encoding.
112 *
113 * @param algorithm the name of the algorithm requested.
114 * See Appendix A in the <a href=
115 * "../../../technotes/guides/security/crypto/CryptoSpec.html#AppA">
116 * Java Cryptography Architecture API Specification & Reference </a>
117 * for information about standard algorithm names.
118 *
119 * @return the new parameter object.
120 *
121 * @exception NoSuchAlgorithmException if no Provider supports an
122 * AlgorithmParametersSpi implementation for the
123 * specified algorithm.
124 *
125 * @see Provider
126 */
127 public static AlgorithmParameters getInstance(String algorithm)
128 throws NoSuchAlgorithmException {
129 try {
130 Object[] objs = Security.getImpl(algorithm, "AlgorithmParameters",
131 (String)null);
132 return new AlgorithmParameters((AlgorithmParametersSpi)objs[0],
133 (Provider)objs[1],
134 algorithm);
135 } catch(NoSuchProviderException e) {
136 throw new NoSuchAlgorithmException(algorithm + " not found");
137 }
138 }
139
140 /**
141 * Returns a parameter object for the specified algorithm.
142 *
143 * <p> A new AlgorithmParameters object encapsulating the
144 * AlgorithmParametersSpi implementation from the specified provider
145 * is returned. The specified provider must be registered
146 * in the security provider list.
147 *
148 * <p> Note that the list of registered providers may be retrieved via
149 * the {@link Security#getProviders() Security.getProviders()} method.
150 *
151 * <p>The returned parameter object must be initialized via a call to
152 * <code>init</code>, using an appropriate parameter specification or
153 * parameter encoding.
154 *
155 * @param algorithm the name of the algorithm requested.
156 * See Appendix A in the <a href=
157 * "../../../technotes/guides/security/crypto/CryptoSpec.html#AppA">
158 * Java Cryptography Architecture API Specification & Reference </a>
159 * for information about standard algorithm names.
160 *
161 * @param provider the name of the provider.
162 *
163 * @return the new parameter object.
164 *
165 * @exception NoSuchAlgorithmException if an AlgorithmParametersSpi
166 * implementation for the specified algorithm is not
167 * available from the specified provider.
168 *
169 * @exception NoSuchProviderException if the specified provider is not
170 * registered in the security provider list.
171 *
172 * @exception IllegalArgumentException if the provider name is null
173 * or empty.
174 *
175 * @see Provider
176 */
177 public static AlgorithmParameters getInstance(String algorithm,
178 String provider)
179 throws NoSuchAlgorithmException, NoSuchProviderException
180 {
181 if (provider == null || provider.length() == 0)
182 throw new IllegalArgumentException("missing provider");
183 Object[] objs = Security.getImpl(algorithm, "AlgorithmParameters",
184 provider);
185 return new AlgorithmParameters((AlgorithmParametersSpi)objs[0],
186 (Provider)objs[1],
187 algorithm);
188 }
189
190 /**
191 * Returns a parameter object for the specified algorithm.
192 *
193 * <p> A new AlgorithmParameters object encapsulating the
194 * AlgorithmParametersSpi implementation from the specified Provider
195 * object is returned. Note that the specified Provider object
196 * does not have to be registered in the provider list.
197 *
198 * <p>The returned parameter object must be initialized via a call to
199 * <code>init</code>, using an appropriate parameter specification or
200 * parameter encoding.
201 *
202 * @param algorithm the name of the algorithm requested.
203 * See Appendix A in the <a href=
204 * "../../../technotes/guides/security/crypto/CryptoSpec.html#AppA">
205 * Java Cryptography Architecture API Specification & Reference </a>
206 * for information about standard algorithm names.
207 *
208 * @param provider the name of the provider.
209 *
210 * @return the new parameter object.
211 *
212 * @exception NoSuchAlgorithmException if an AlgorithmParameterGeneratorSpi
213 * implementation for the specified algorithm is not available
214 * from the specified Provider object.
215 *
216 * @exception IllegalArgumentException if the provider is null.
217 *
218 * @see Provider
219 *
220 * @since 1.4
221 */
222 public static AlgorithmParameters getInstance(String algorithm,
223 Provider provider)
224 throws NoSuchAlgorithmException
225 {
226 if (provider == null)
227 throw new IllegalArgumentException("missing provider");
228 Object[] objs = Security.getImpl(algorithm, "AlgorithmParameters",
229 provider);
230 return new AlgorithmParameters((AlgorithmParametersSpi)objs[0],
231 (Provider)objs[1],
232 algorithm);
233 }
234
235 /**
236 * Returns the provider of this parameter object.
237 *
238 * @return the provider of this parameter object
239 */
240 public final Provider getProvider() {
241 return this.provider;
242 }
243
244 /**
245 * Initializes this parameter object using the parameters
246 * specified in <code>paramSpec</code>.
247 *
248 * @param paramSpec the parameter specification.
249 *
250 * @exception InvalidParameterSpecException if the given parameter
251 * specification is inappropriate for the initialization of this parameter
252 * object, or if this parameter object has already been initialized.
253 */
254 public final void init(AlgorithmParameterSpec paramSpec)
255 throws InvalidParameterSpecException
256 {
257 if (this.initialized)
258 throw new InvalidParameterSpecException("already initialized");
259 paramSpi.engineInit(paramSpec);
260 this.initialized = true;
261 }
262
263 /**
264 * Imports the specified parameters and decodes them according to the
265 * primary decoding format for parameters. The primary decoding
266 * format for parameters is ASN.1, if an ASN.1 specification for this type
267 * of parameters exists.
268 *
269 * @param params the encoded parameters.
270 *
271 * @exception IOException on decoding errors, or if this parameter object
272 * has already been initialized.
273 */
274 public final void init(byte[] params) throws IOException {
275 if (this.initialized)
276 throw new IOException("already initialized");
277 paramSpi.engineInit(params);
278 this.initialized = true;
279 }
280
281 /**
282 * Imports the parameters from <code>params</code> and decodes them
283 * according to the specified decoding scheme.
284 * If <code>format</code> is null, the
285 * primary decoding format for parameters is used. The primary decoding
286 * format is ASN.1, if an ASN.1 specification for these parameters
287 * exists.
288 *
289 * @param params the encoded parameters.
290 *
291 * @param format the name of the decoding scheme.
292 *
293 * @exception IOException on decoding errors, or if this parameter object
294 * has already been initialized.
295 */
296 public final void init(byte[] params, String format) throws IOException {
297 if (this.initialized)
298 throw new IOException("already initialized");
299 paramSpi.engineInit(params, format);
300 this.initialized = true;
301 }
302
303 /**
304 * Returns a (transparent) specification of this parameter object.
305 * <code>paramSpec</code> identifies the specification class in which
306 * the parameters should be returned. It could, for example, be
307 * <code>DSAParameterSpec.class</code>, to indicate that the
308 * parameters should be returned in an instance of the
309 * <code>DSAParameterSpec</code> class.
310 *
311 * @param paramSpec the specification class in which
312 * the parameters should be returned.
313 *
314 * @return the parameter specification.
315 *
316 * @exception InvalidParameterSpecException if the requested parameter
317 * specification is inappropriate for this parameter object, or if this
318 * parameter object has not been initialized.
319 */
320 public final <T extends AlgorithmParameterSpec>
321 T getParameterSpec(Class<T> paramSpec)
322 throws InvalidParameterSpecException
323 {
324 if (this.initialized == false) {
325 throw new InvalidParameterSpecException("not initialized");
326 }
327 return paramSpi.engineGetParameterSpec(paramSpec);
328 }
329
330 /**
331 * Returns the parameters in their primary encoding format.
332 * The primary encoding format for parameters is ASN.1, if an ASN.1
333 * specification for this type of parameters exists.
334 *
335 * @return the parameters encoded using their primary encoding format.
336 *
337 * @exception IOException on encoding errors, or if this parameter object
338 * has not been initialized.
339 */
340 public final byte[] getEncoded() throws IOException
341 {
342 if (this.initialized == false) {
343 throw new IOException("not initialized");
344 }
345 return paramSpi.engineGetEncoded();
346 }
347
348 /**
349 * Returns the parameters encoded in the specified scheme.
350 * If <code>format</code> is null, the
351 * primary encoding format for parameters is used. The primary encoding
352 * format is ASN.1, if an ASN.1 specification for these parameters
353 * exists.
354 *
355 * @param format the name of the encoding format.
356 *
357 * @return the parameters encoded using the specified encoding scheme.
358 *
359 * @exception IOException on encoding errors, or if this parameter object
360 * has not been initialized.
361 */
362 public final byte[] getEncoded(String format) throws IOException
363 {
364 if (this.initialized == false) {
365 throw new IOException("not initialized");
366 }
367 return paramSpi.engineGetEncoded(format);
368 }
369
370 /**
371 * Returns a formatted string describing the parameters.
372 *
373 * @return a formatted string describing the parameters, or null if this
374 * parameter object has not been initialized.
375 */
376 public final String toString() {
377 if (this.initialized == false) {
378 return null;
379 }
380 return paramSpi.engineToString();
381 }
382 }
Save This Page