001 /*
002 * Copyright 1997-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.security;
027
028 import java.io.*;
029 import java.security.spec.AlgorithmParameterSpec;
030 import java.security.spec.InvalidParameterSpecException;
031
032 /**
033 * This class is used as an opaque representation of cryptographic parameters.
034 *
035 * <p>An <code>AlgorithmParameters</code> object for managing the parameters
036 * for a particular algorithm can be obtained by
037 * calling one of the <code>getInstance</code> factory methods
038 * (static methods that return instances of a given class).
039 *
040 * <p>Once an <code>AlgorithmParameters</code> object is obtained, it must be
041 * initialized via a call to <code>init</code>, using an appropriate parameter
042 * specification or parameter encoding.
043 *
044 * <p>A transparent parameter specification is obtained from an
045 * <code>AlgorithmParameters</code> object via a call to
046 * <code>getParameterSpec</code>, and a byte encoding of the parameters is
047 * obtained via a call to <code>getEncoded</code>.
048 *
049 * @author Jan Luehe
050 *
051 * @version 1.33, 05/05/07
052 *
053 * @see java.security.spec.AlgorithmParameterSpec
054 * @see java.security.spec.DSAParameterSpec
055 * @see KeyPairGenerator
056 *
057 * @since 1.2
058 */
059
060 public class AlgorithmParameters {
061
062 // The provider
063 private Provider provider;
064
065 // The provider implementation (delegate)
066 private AlgorithmParametersSpi paramSpi;
067
068 // The algorithm
069 private String algorithm;
070
071 // Has this object been initialized?
072 private boolean initialized = false;
073
074 /**
075 * Creates an AlgorithmParameters object.
076 *
077 * @param paramSpi the delegate
078 * @param provider the provider
079 * @param algorithm the algorithm
080 */
081 protected AlgorithmParameters(AlgorithmParametersSpi paramSpi,
082 Provider provider, String algorithm) {
083 this .paramSpi = paramSpi;
084 this .provider = provider;
085 this .algorithm = algorithm;
086 }
087
088 /**
089 * Returns the name of the algorithm associated with this parameter object.
090 *
091 * @return the algorithm name.
092 */
093 public final String getAlgorithm() {
094 return this .algorithm;
095 }
096
097 /**
098 * Returns a parameter object for the specified algorithm.
099 *
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,
131 "AlgorithmParameters", (String) null);
132 return new AlgorithmParameters(
133 (AlgorithmParametersSpi) objs[0],
134 (Provider) objs[1], 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) throws NoSuchAlgorithmException,
179 NoSuchProviderException {
180 if (provider == null || provider.length() == 0)
181 throw new IllegalArgumentException("missing provider");
182 Object[] objs = Security.getImpl(algorithm,
183 "AlgorithmParameters", provider);
184 return new AlgorithmParameters(
185 (AlgorithmParametersSpi) objs[0], (Provider) objs[1],
186 algorithm);
187 }
188
189 /**
190 * Returns a parameter object for the specified algorithm.
191 *
192 * <p> A new AlgorithmParameters object encapsulating the
193 * AlgorithmParametersSpi implementation from the specified Provider
194 * object is returned. Note that the specified Provider object
195 * does not have to be registered in the provider list.
196 *
197 * <p>The returned parameter object must be initialized via a call to
198 * <code>init</code>, using an appropriate parameter specification or
199 * parameter encoding.
200 *
201 * @param algorithm the name of the algorithm requested.
202 * See Appendix A in the <a href=
203 * "../../../technotes/guides/security/crypto/CryptoSpec.html#AppA">
204 * Java Cryptography Architecture API Specification & Reference </a>
205 * for information about standard algorithm names.
206 *
207 * @param provider the name of the provider.
208 *
209 * @return the new parameter object.
210 *
211 * @exception NoSuchAlgorithmException if an AlgorithmParameterGeneratorSpi
212 * implementation for the specified algorithm is not available
213 * from the specified Provider object.
214 *
215 * @exception IllegalArgumentException if the provider is null.
216 *
217 * @see Provider
218 *
219 * @since 1.4
220 */
221 public static AlgorithmParameters getInstance(String algorithm,
222 Provider provider) throws NoSuchAlgorithmException {
223 if (provider == null)
224 throw new IllegalArgumentException("missing provider");
225 Object[] objs = Security.getImpl(algorithm,
226 "AlgorithmParameters", provider);
227 return new AlgorithmParameters(
228 (AlgorithmParametersSpi) objs[0], (Provider) objs[1],
229 algorithm);
230 }
231
232 /**
233 * Returns the provider of this parameter object.
234 *
235 * @return the provider of this parameter object
236 */
237 public final Provider getProvider() {
238 return this .provider;
239 }
240
241 /**
242 * Initializes this parameter object using the parameters
243 * specified in <code>paramSpec</code>.
244 *
245 * @param paramSpec the parameter specification.
246 *
247 * @exception InvalidParameterSpecException if the given parameter
248 * specification is inappropriate for the initialization of this parameter
249 * object, or if this parameter object has already been initialized.
250 */
251 public final void init(AlgorithmParameterSpec paramSpec)
252 throws InvalidParameterSpecException {
253 if (this .initialized)
254 throw new InvalidParameterSpecException(
255 "already initialized");
256 paramSpi.engineInit(paramSpec);
257 this .initialized = true;
258 }
259
260 /**
261 * Imports the specified parameters and decodes them according to the
262 * primary decoding format for parameters. The primary decoding
263 * format for parameters is ASN.1, if an ASN.1 specification for this type
264 * of parameters exists.
265 *
266 * @param params the encoded parameters.
267 *
268 * @exception IOException on decoding errors, or if this parameter object
269 * has already been initialized.
270 */
271 public final void init(byte[] params) throws IOException {
272 if (this .initialized)
273 throw new IOException("already initialized");
274 paramSpi.engineInit(params);
275 this .initialized = true;
276 }
277
278 /**
279 * Imports the parameters from <code>params</code> and decodes them
280 * according to the specified decoding scheme.
281 * If <code>format</code> is null, the
282 * primary decoding format for parameters is used. The primary decoding
283 * format is ASN.1, if an ASN.1 specification for these parameters
284 * exists.
285 *
286 * @param params the encoded parameters.
287 *
288 * @param format the name of the decoding scheme.
289 *
290 * @exception IOException on decoding errors, or if this parameter object
291 * has already been initialized.
292 */
293 public final void init(byte[] params, String format)
294 throws IOException {
295 if (this .initialized)
296 throw new IOException("already initialized");
297 paramSpi.engineInit(params, format);
298 this .initialized = true;
299 }
300
301 /**
302 * Returns a (transparent) specification of this parameter object.
303 * <code>paramSpec</code> identifies the specification class in which
304 * the parameters should be returned. It could, for example, be
305 * <code>DSAParameterSpec.class</code>, to indicate that the
306 * parameters should be returned in an instance of the
307 * <code>DSAParameterSpec</code> class.
308 *
309 * @param paramSpec the specification class in which
310 * the parameters should be returned.
311 *
312 * @return the parameter specification.
313 *
314 * @exception InvalidParameterSpecException if the requested parameter
315 * specification is inappropriate for this parameter object, or if this
316 * parameter object has not been initialized.
317 */
318 public final <T extends AlgorithmParameterSpec> T getParameterSpec(
319 Class<T> paramSpec) throws InvalidParameterSpecException {
320 if (this .initialized == false) {
321 throw new InvalidParameterSpecException("not initialized");
322 }
323 return paramSpi.engineGetParameterSpec(paramSpec);
324 }
325
326 /**
327 * Returns the parameters in their primary encoding format.
328 * The primary encoding format for parameters is ASN.1, if an ASN.1
329 * specification for this type of parameters exists.
330 *
331 * @return the parameters encoded using their primary encoding format.
332 *
333 * @exception IOException on encoding errors, or if this parameter object
334 * has not been initialized.
335 */
336 public final byte[] getEncoded() throws IOException {
337 if (this .initialized == false) {
338 throw new IOException("not initialized");
339 }
340 return paramSpi.engineGetEncoded();
341 }
342
343 /**
344 * Returns the parameters encoded in the specified scheme.
345 * If <code>format</code> is null, the
346 * primary encoding format for parameters is used. The primary encoding
347 * format is ASN.1, if an ASN.1 specification for these parameters
348 * exists.
349 *
350 * @param format the name of the encoding format.
351 *
352 * @return the parameters encoded using the specified encoding scheme.
353 *
354 * @exception IOException on encoding errors, or if this parameter object
355 * has not been initialized.
356 */
357 public final byte[] getEncoded(String format) throws IOException {
358 if (this .initialized == false) {
359 throw new IOException("not initialized");
360 }
361 return paramSpi.engineGetEncoded(format);
362 }
363
364 /**
365 * Returns a formatted string describing the parameters.
366 *
367 * @return a formatted string describing the parameters, or null if this
368 * parameter object has not been initialized.
369 */
370 public final String toString() {
371 if (this .initialized == false) {
372 return null;
373 }
374 return paramSpi.engineToString();
375 }
376 }
|