001: /*
002: * @(#)AlgorithmParameters.java 1.26 06/10/10
003: *
004: * Copyright 1990-2006 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: *
026: */
027:
028: package java.security;
029:
030: import java.io.*;
031: import java.security.spec.AlgorithmParameterSpec;
032: import java.security.spec.InvalidParameterSpecException;
033:
034: /**
035: * This class is used as an opaque representation of cryptographic parameters.
036: *
037: * <p>An <code>AlgorithmParameters</code> object for managing the parameters
038: * for a particular algorithm can be obtained by
039: * calling one of the <code>getInstance</code> factory methods
040: * (static methods that return instances of a given class).
041: *
042: * <p>There are two ways to request such an implementation: by
043: * specifying either just an algorithm name, or both an algorithm name
044: * and a package provider.
045: *
046: * <ul>
047: *
048: * <li>If just an algorithm name is specified, the system will
049: * determine if there is an AlgorithmParameters
050: * implementation for the algorithm requested
051: * available in the environment, and if there is more than one, if
052: * there is a preferred one.
053: *
054: * <li>If both an algorithm name and a package provider are specified,
055: * the system will determine if there is an implementation
056: * in the package requested, and throw an exception if there
057: * is not.
058: *
059: * </ul>
060: *
061: * <p>Once an <code>AlgorithmParameters</code> object is returned, it must be
062: * initialized via a call to <code>init</code>, using an appropriate parameter
063: * specification or parameter encoding.
064: *
065: * <p>A transparent parameter specification is obtained from an
066: * <code>AlgorithmParameters</code> object via a call to
067: * <code>getParameterSpec</code>, and a byte encoding of the parameters is
068: * obtained via a call to <code>getEncoded</code>.
069: *
070: * @author Jan Luehe
071: *
072: * @version 1.19, 02/02/00
073: *
074: * @see java.security.spec.AlgorithmParameterSpec
075: * @see java.security.spec.DSAParameterSpec
076: * @see KeyPairGenerator
077: *
078: * @since 1.2
079: */
080:
081: public class AlgorithmParameters {
082:
083: // The provider
084: private Provider provider;
085:
086: // The provider implementation (delegate)
087: private AlgorithmParametersSpi paramSpi;
088:
089: // The algorithm
090: private String algorithm;
091:
092: // Has this object been initialized?
093: private boolean initialized = false;
094:
095: /**
096: * Creates an AlgorithmParameters object.
097: *
098: * @param paramSpi the delegate
099: * @param provider the provider
100: * @param algorithm the algorithm
101: */
102: protected AlgorithmParameters(AlgorithmParametersSpi paramSpi,
103: Provider provider, String algorithm) {
104: this .paramSpi = paramSpi;
105: this .provider = provider;
106: this .algorithm = algorithm;
107: }
108:
109: /**
110: * Returns the name of the algorithm associated with this parameter object.
111: *
112: * @return the algorithm name.
113: */
114: public final String getAlgorithm() {
115: return this .algorithm;
116: }
117:
118: /**
119: * Generates a parameter object for the specified algorithm.
120: *
121: * <p>If the default provider package provides an implementation of the
122: * requested algorithm, an instance of AlgorithmParameters containing that
123: * implementation is returned.
124: * If the algorithm is not available in the default
125: * package, other packages are searched.
126: *
127: * <p>The returned parameter object must be initialized via a call to
128: * <code>init</code>, using an appropriate parameter specification or
129: * parameter encoding.
130: *
131: * @param algorithm the name of the algorithm requested.
132: *
133: * @return the new parameter object.
134: *
135: * @exception NoSuchAlgorithmException if the algorithm is
136: * not available in the environment.
137: */
138: public static AlgorithmParameters getInstance(String algorithm)
139: throws NoSuchAlgorithmException {
140: try {
141: Object[] objs = Security.getImpl(algorithm,
142: "AlgorithmParameters", (String) null);
143: return new AlgorithmParameters(
144: (AlgorithmParametersSpi) objs[0],
145: (Provider) objs[1], algorithm);
146: } catch (NoSuchProviderException e) {
147: throw new NoSuchAlgorithmException(algorithm + " not found");
148: }
149: }
150:
151: /**
152: * Generates a parameter object for the specified algorithm, as supplied
153: * by the specified provider, if such an algorithm is available from the
154: * provider.
155: *
156: * <p>The returned parameter object must be initialized via a call to
157: * <code>init</code>, using an appropriate parameter specification or
158: * parameter encoding.
159: *
160: * @param algorithm the name of the algorithm requested.
161: *
162: * @param provider the name of the provider.
163: *
164: * @return the new parameter object.
165: *
166: * @exception NoSuchAlgorithmException if the algorithm is
167: * not available in the package supplied by the requested
168: * provider.
169: *
170: * @exception NoSuchProviderException if the provider is not
171: * available in the environment.
172: *
173: * @exception IllegalArgumentException if the provider name is null
174: * or empty.
175: *
176: * @see Provider
177: */
178: public static AlgorithmParameters getInstance(String algorithm,
179: String provider) throws NoSuchAlgorithmException,
180: NoSuchProviderException {
181: if (provider == null || provider.length() == 0)
182: throw new IllegalArgumentException("missing provider");
183: Object[] objs = Security.getImpl(algorithm,
184: "AlgorithmParameters", provider);
185: return new AlgorithmParameters(
186: (AlgorithmParametersSpi) objs[0], (Provider) objs[1],
187: algorithm);
188: }
189:
190: /**
191: * Generates a parameter object for the specified algorithm, as supplied
192: * by the specified provider, if such an algorithm is available from the
193: * provider. Note: the <code>provider</code> doesn't have to be registered.
194: *
195: * <p>The returned parameter object must be initialized via a call to
196: * <code>init</code>, using an appropriate parameter specification or
197: * parameter encoding.
198: *
199: * @param algorithm the name of the algorithm requested.
200: *
201: * @param provider the name of the provider.
202: *
203: * @return the new parameter object.
204: *
205: * @exception NoSuchAlgorithmException if the algorithm is
206: * not available in the package supplied by the requested
207: * provider.
208: *
209: * @exception IllegalArgumentException if the <code>provider</code> is
210: * null.
211: *
212: * @see Provider
213: *
214: * @since 1.4
215: */
216: public static AlgorithmParameters getInstance(String algorithm,
217: Provider provider) throws NoSuchAlgorithmException {
218: if (provider == null)
219: throw new IllegalArgumentException("missing provider");
220: Object[] objs = Security.getImpl(algorithm,
221: "AlgorithmParameters", provider);
222: return new AlgorithmParameters(
223: (AlgorithmParametersSpi) objs[0], (Provider) objs[1],
224: algorithm);
225: }
226:
227: /**
228: * Returns the provider of this parameter object.
229: *
230: * @return the provider of this parameter object
231: */
232: public final Provider getProvider() {
233: return this .provider;
234: }
235:
236: /**
237: * Initializes this parameter object using the parameters
238: * specified in <code>paramSpec</code>.
239: *
240: * @param paramSpec the parameter specification.
241: *
242: * @exception InvalidParameterSpecException if the given parameter
243: * specification is inappropriate for the initialization of this parameter
244: * object, or if this parameter object has already been initialized.
245: */
246: public final void init(AlgorithmParameterSpec paramSpec)
247: throws InvalidParameterSpecException {
248: if (this .initialized)
249: throw new InvalidParameterSpecException(
250: "already initialized");
251: paramSpi.engineInit(paramSpec);
252: this .initialized = true;
253: }
254:
255: /**
256: * Imports the specified parameters and decodes them according to the
257: * primary decoding format for parameters. The primary decoding
258: * format for parameters is ASN.1, if an ASN.1 specification for this type
259: * of parameters exists.
260: *
261: * @param params the encoded parameters.
262: *
263: * @exception IOException on decoding errors, or if this parameter object
264: * has already been initialized.
265: */
266: public final void init(byte[] params) throws IOException {
267: if (this .initialized)
268: throw new IOException("already initialized");
269: paramSpi.engineInit(params);
270: this .initialized = true;
271: }
272:
273: /**
274: * Imports the parameters from <code>params</code> and decodes them
275: * according to the specified decoding scheme.
276: * If <code>format</code> is null, the
277: * primary decoding format for parameters is used. The primary decoding
278: * format is ASN.1, if an ASN.1 specification for these parameters
279: * exists.
280: *
281: * @param params the encoded parameters.
282: *
283: * @param format the name of the decoding scheme.
284: *
285: * @exception IOException on decoding errors, or if this parameter object
286: * has already been initialized.
287: */
288: public final void init(byte[] params, String format)
289: throws IOException {
290: if (this .initialized)
291: throw new IOException("already initialized");
292: paramSpi.engineInit(params, format);
293: this .initialized = true;
294: }
295:
296: /**
297: * Returns a (transparent) specification of this parameter object.
298: * <code>paramSpec</code> identifies the specification class in which
299: * the parameters should be returned. It could, for example, be
300: * <code>DSAParameterSpec.class</code>, to indicate that the
301: * parameters should be returned in an instance of the
302: * <code>DSAParameterSpec</code> class.
303: *
304: * @param paramSpec the specification class in which
305: * the parameters should be returned.
306: *
307: * @return the parameter specification.
308: *
309: * @exception InvalidParameterSpecException if the requested parameter
310: * specification is inappropriate for this parameter object, or if this
311: * parameter object has not been initialized.
312: */
313: public final AlgorithmParameterSpec getParameterSpec(Class paramSpec)
314: throws InvalidParameterSpecException {
315: if (this .initialized == false) {
316: throw new InvalidParameterSpecException("not initialized");
317: }
318: return paramSpi.engineGetParameterSpec(paramSpec);
319: }
320:
321: /**
322: * Returns the parameters in their primary encoding format.
323: * The primary encoding format for parameters is ASN.1, if an ASN.1
324: * specification for this type of parameters exists.
325: *
326: * @return the parameters encoded using their primary encoding format.
327: *
328: * @exception IOException on encoding errors, or if this parameter object
329: * has not been initialized.
330: */
331: public final byte[] getEncoded() throws IOException {
332: if (this .initialized == false) {
333: throw new IOException("not initialized");
334: }
335: return paramSpi.engineGetEncoded();
336: }
337:
338: /**
339: * Returns the parameters encoded in the specified scheme.
340: * If <code>format</code> is null, the
341: * primary encoding format for parameters is used. The primary encoding
342: * format is ASN.1, if an ASN.1 specification for these parameters
343: * exists.
344: *
345: * @param format the name of the encoding format.
346: *
347: * @return the parameters encoded using the specified encoding scheme.
348: *
349: * @exception IOException on encoding errors, or if this parameter object
350: * has not been initialized.
351: */
352: public final byte[] getEncoded(String format) throws IOException {
353: if (this .initialized == false) {
354: throw new IOException("not initialized");
355: }
356: return paramSpi.engineGetEncoded(format);
357: }
358:
359: /**
360: * Returns a formatted string describing the parameters.
361: *
362: * @return a formatted string describing the parameters, or null if this
363: * parameter object has not been initialized.
364: */
365: public final String toString() {
366: if (this .initialized == false) {
367: return null;
368: }
369: return paramSpi.engineToString();
370: }
371: }
|