KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > security > AlgorithmParameters


1 /*
2  * @(#)AlgorithmParameters.java 1.24 04/05/05
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */

7  
8 package java.security;
9
10 import java.io.*;
11 import java.security.spec.AlgorithmParameterSpec JavaDoc;
12 import java.security.spec.InvalidParameterSpecException JavaDoc;
13
14 /**
15  * This class is used as an opaque representation of cryptographic parameters.
16  *
17  * <p>An <code>AlgorithmParameters</code> object for managing the parameters
18  * for a particular algorithm can be obtained by
19  * calling one of the <code>getInstance</code> factory methods
20  * (static methods that return instances of a given class).
21  *
22  * <p>There are two ways to request such an implementation: by
23  * specifying either just an algorithm name, or both an algorithm name
24  * and a package provider.
25  *
26  * <ul>
27  *
28  * <li>If just an algorithm name is specified, the system will
29  * determine if there is an AlgorithmParameters
30  * implementation for the algorithm requested
31  * available in the environment, and if there is more than one, if
32  * there is a preferred one.
33  *
34  * <li>If both an algorithm name and a package provider are specified,
35  * the system will determine if there is an implementation
36  * in the package requested, and throw an exception if there
37  * is not.
38  *
39  * </ul>
40  *
41  * <p>Once an <code>AlgorithmParameters</code> object is returned, it must be
42  * initialized via a call to <code>init</code>, using an appropriate parameter
43  * specification or parameter encoding.
44  *
45  * <p>A transparent parameter specification is obtained from an
46  * <code>AlgorithmParameters</code> object via a call to
47  * <code>getParameterSpec</code>, and a byte encoding of the parameters is
48  * obtained via a call to <code>getEncoded</code>.
49  *
50  * @author Jan Luehe
51  *
52  * @version 1.24, 05/05/04
53  *
54  * @see java.security.spec.AlgorithmParameterSpec
55  * @see java.security.spec.DSAParameterSpec
56  * @see KeyPairGenerator
57  *
58  * @since 1.2
59  */

60
61 public class AlgorithmParameters {
62
63     // The provider
64
private Provider JavaDoc provider;
65
66     // The provider implementation (delegate)
67
private AlgorithmParametersSpi JavaDoc paramSpi;
68
69     // The algorithm
70
private String JavaDoc algorithm;
71
72     // Has this object been initialized?
73
private boolean initialized = false;
74
75     /**
76      * Creates an AlgorithmParameters object.
77      *
78      * @param paramSpi the delegate
79      * @param provider the provider
80      * @param algorithm the algorithm
81      */

82     protected AlgorithmParameters(AlgorithmParametersSpi JavaDoc paramSpi,
83                   Provider JavaDoc provider, String JavaDoc algorithm)
84     {
85     this.paramSpi = paramSpi;
86     this.provider = provider;
87     this.algorithm = algorithm;
88     }
89
90     /**
91      * Returns the name of the algorithm associated with this parameter object.
92      *
93      * @return the algorithm name.
94      */

95     public final String JavaDoc getAlgorithm() {
96         return this.algorithm;
97     }
98
99     /**
100      * Generates a parameter object for the specified algorithm.
101      *
102      * <p>If the default provider package provides an implementation of the
103      * requested algorithm, an instance of AlgorithmParameters containing that
104      * implementation is returned.
105      * If the algorithm is not available in the default
106      * package, other packages are searched.
107      *
108      * <p>The returned parameter object must be initialized via a call to
109      * <code>init</code>, using an appropriate parameter specification or
110      * parameter encoding.
111      *
112      * @param algorithm the name of the algorithm requested.
113      *
114      * @return the new parameter object.
115      *
116      * @exception NoSuchAlgorithmException if the algorithm is
117      * not available in the environment.
118      */

119     public static AlgorithmParameters JavaDoc getInstance(String JavaDoc algorithm)
120     throws NoSuchAlgorithmException JavaDoc {
121     try {
122         Object JavaDoc[] objs = Security.getImpl(algorithm, "AlgorithmParameters",
123                          (String JavaDoc)null);
124         return new AlgorithmParameters JavaDoc((AlgorithmParametersSpi JavaDoc)objs[0],
125                        (Provider JavaDoc)objs[1],
126                        algorithm);
127     } catch(NoSuchProviderException JavaDoc e) {
128         throw new NoSuchAlgorithmException JavaDoc(algorithm + " not found");
129     }
130     }
131
132     /**
133      * Generates a parameter object for the specified algorithm, as supplied
134      * by the specified provider, if such an algorithm is available from the
135      * provider.
136      *
137      * <p>The returned parameter object must be initialized via a call to
138      * <code>init</code>, using an appropriate parameter specification or
139      * parameter encoding.
140      *
141      * @param algorithm the name of the algorithm requested.
142      *
143      * @param provider the name of the provider.
144      *
145      * @return the new parameter object.
146      *
147      * @exception NoSuchAlgorithmException if the algorithm is
148      * not available in the package supplied by the requested
149      * provider.
150      *
151      * @exception NoSuchProviderException if the provider is not
152      * available in the environment.
153      *
154      * @exception IllegalArgumentException if the provider name is null
155      * or empty.
156      *
157      * @see Provider
158      */

159     public static AlgorithmParameters JavaDoc getInstance(String JavaDoc algorithm,
160                           String JavaDoc provider)
161     throws NoSuchAlgorithmException JavaDoc, NoSuchProviderException JavaDoc
162     {
163     if (provider == null || provider.length() == 0)
164         throw new IllegalArgumentException JavaDoc("missing provider");
165     Object JavaDoc[] objs = Security.getImpl(algorithm, "AlgorithmParameters",
166                      provider);
167     return new AlgorithmParameters JavaDoc((AlgorithmParametersSpi JavaDoc)objs[0],
168                        (Provider JavaDoc)objs[1],
169                        algorithm);
170     }
171
172     /**
173      * Generates a parameter object for the specified algorithm, as supplied
174      * by the specified provider, if such an algorithm is available from the
175      * provider. Note: the <code>provider</code> doesn't have to be registered.
176      *
177      * <p>The returned parameter object must be initialized via a call to
178      * <code>init</code>, using an appropriate parameter specification or
179      * parameter encoding.
180      *
181      * @param algorithm the name of the algorithm requested.
182      *
183      * @param provider the name of the provider.
184      *
185      * @return the new parameter object.
186      *
187      * @exception NoSuchAlgorithmException if the algorithm is
188      * not available in the package supplied by the requested
189      * provider.
190      *
191      * @exception IllegalArgumentException if the <code>provider</code> is
192      * null.
193      *
194      * @see Provider
195      *
196      * @since 1.4
197      */

198     public static AlgorithmParameters JavaDoc getInstance(String JavaDoc algorithm,
199                           Provider JavaDoc provider)
200     throws NoSuchAlgorithmException JavaDoc
201     {
202     if (provider == null)
203         throw new IllegalArgumentException JavaDoc("missing provider");
204     Object JavaDoc[] objs = Security.getImpl(algorithm, "AlgorithmParameters",
205                      provider);
206     return new AlgorithmParameters JavaDoc((AlgorithmParametersSpi JavaDoc)objs[0],
207                        (Provider JavaDoc)objs[1],
208                        algorithm);
209     }
210
211     /**
212      * Returns the provider of this parameter object.
213      *
214      * @return the provider of this parameter object
215      */

216     public final Provider JavaDoc getProvider() {
217     return this.provider;
218     }
219
220     /**
221      * Initializes this parameter object using the parameters
222      * specified in <code>paramSpec</code>.
223      *
224      * @param paramSpec the parameter specification.
225      *
226      * @exception InvalidParameterSpecException if the given parameter
227      * specification is inappropriate for the initialization of this parameter
228      * object, or if this parameter object has already been initialized.
229      */

230     public final void init(AlgorithmParameterSpec JavaDoc paramSpec)
231     throws InvalidParameterSpecException JavaDoc
232     {
233     if (this.initialized)
234         throw new InvalidParameterSpecException JavaDoc("already initialized");
235     paramSpi.engineInit(paramSpec);
236     this.initialized = true;
237     }
238
239     /**
240      * Imports the specified parameters and decodes them according to the
241      * primary decoding format for parameters. The primary decoding
242      * format for parameters is ASN.1, if an ASN.1 specification for this type
243      * of parameters exists.
244      *
245      * @param params the encoded parameters.
246      *
247      * @exception IOException on decoding errors, or if this parameter object
248      * has already been initialized.
249      */

250     public final void init(byte[] params) throws IOException {
251     if (this.initialized)
252         throw new IOException("already initialized");
253     paramSpi.engineInit(params);
254     this.initialized = true;
255     }
256
257     /**
258      * Imports the parameters from <code>params</code> and decodes them
259      * according to the specified decoding scheme.
260      * If <code>format</code> is null, the
261      * primary decoding format for parameters is used. The primary decoding
262      * format is ASN.1, if an ASN.1 specification for these parameters
263      * exists.
264      *
265      * @param params the encoded parameters.
266      *
267      * @param format the name of the decoding scheme.
268      *
269      * @exception IOException on decoding errors, or if this parameter object
270      * has already been initialized.
271      */

272     public final void init(byte[] params, String JavaDoc format) throws IOException {
273     if (this.initialized)
274         throw new IOException("already initialized");
275     paramSpi.engineInit(params, format);
276     this.initialized = true;
277     }
278
279     /**
280      * Returns a (transparent) specification of this parameter object.
281      * <code>paramSpec</code> identifies the specification class in which
282      * the parameters should be returned. It could, for example, be
283      * <code>DSAParameterSpec.class</code>, to indicate that the
284      * parameters should be returned in an instance of the
285      * <code>DSAParameterSpec</code> class.
286      *
287      * @param paramSpec the specification class in which
288      * the parameters should be returned.
289      *
290      * @return the parameter specification.
291      *
292      * @exception InvalidParameterSpecException if the requested parameter
293      * specification is inappropriate for this parameter object, or if this
294      * parameter object has not been initialized.
295      */

296     public final <T extends AlgorithmParameterSpec JavaDoc>
297     T getParameterSpec(Class JavaDoc<T> paramSpec)
298     throws InvalidParameterSpecException JavaDoc
299     {
300     if (this.initialized == false) {
301         throw new InvalidParameterSpecException JavaDoc("not initialized");
302     }
303     return paramSpi.engineGetParameterSpec(paramSpec);
304     }
305
306     /**
307      * Returns the parameters in their primary encoding format.
308      * The primary encoding format for parameters is ASN.1, if an ASN.1
309      * specification for this type of parameters exists.
310      *
311      * @return the parameters encoded using their primary encoding format.
312      *
313      * @exception IOException on encoding errors, or if this parameter object
314      * has not been initialized.
315      */

316     public final byte[] getEncoded() throws IOException
317     {
318     if (this.initialized == false) {
319         throw new IOException("not initialized");
320     }
321     return paramSpi.engineGetEncoded();
322     }
323
324     /**
325      * Returns the parameters encoded in the specified scheme.
326      * If <code>format</code> is null, the
327      * primary encoding format for parameters is used. The primary encoding
328      * format is ASN.1, if an ASN.1 specification for these parameters
329      * exists.
330      *
331      * @param format the name of the encoding format.
332      *
333      * @return the parameters encoded using the specified encoding scheme.
334      *
335      * @exception IOException on encoding errors, or if this parameter object
336      * has not been initialized.
337      */

338     public final byte[] getEncoded(String JavaDoc format) throws IOException
339     {
340     if (this.initialized == false) {
341         throw new IOException("not initialized");
342     }
343     return paramSpi.engineGetEncoded(format);
344     }
345
346     /**
347      * Returns a formatted string describing the parameters.
348      *
349      * @return a formatted string describing the parameters, or null if this
350      * parameter object has not been initialized.
351      */

352     public final String JavaDoc toString() {
353     if (this.initialized == false) {
354         return null;
355     }
356     return paramSpi.engineToString();
357     }
358 }
359
Popular Tags