GNU Classpath (0.20) | |
Frames | No Frames |
1: /* AlgorithmParameters.java --- Algorithm Parameters Implementation Class 2: Copyright (C) 1999, 2003, 2004 Free Software Foundation, Inc. 3: 4: This file is part of GNU Classpath. 5: 6: GNU Classpath is free software; you can redistribute it and/or modify 7: it under the terms of the GNU General Public License as published by 8: the Free Software Foundation; either version 2, or (at your option) 9: any later version. 10: 11: GNU Classpath is distributed in the hope that it will be useful, but 12: WITHOUT ANY WARRANTY; without even the implied warranty of 13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14: General Public License for more details. 15: 16: You should have received a copy of the GNU General Public License 17: along with GNU Classpath; see the file COPYING. If not, write to the 18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 19: 02110-1301 USA. 20: 21: Linking this library statically or dynamically with other modules is 22: making a combined work based on this library. Thus, the terms and 23: conditions of the GNU General Public License cover the whole 24: combination. 25: 26: As a special exception, the copyright holders of this library give you 27: permission to link this library with independent modules to produce an 28: executable, regardless of the license terms of these independent 29: modules, and to copy and distribute the resulting executable under 30: terms of your choice, provided that you also meet, for each linked 31: independent module, the terms and conditions of the license of that 32: module. An independent module is a module which is not derived from 33: or based on this library. If you modify this library, you may extend 34: this exception to your version of the library, but you are not 35: obligated to do so. If you do not wish to do so, delete this 36: exception statement from your version. */ 37: 38: 39: package java.security; 40: 41: import gnu.java.security.Engine; 42: 43: import java.io.IOException; 44: import java.security.spec.AlgorithmParameterSpec; 45: import java.security.spec.InvalidParameterSpecException; 46: 47: /** 48: * <p>This class is used as an opaque representation of cryptographic 49: * parameters.</p> 50: * 51: * <p>An <code>AlgorithmParameters</code> object for managing the parameters 52: * for a particular algorithm can be obtained by calling one of the 53: * <code>getInstance()</code> factory methods (static methods that return 54: * instances of a given class).</p> 55: * 56: * <p>There are two ways to request such an implementation: by specifying 57: * either just an algorithm name, or both an algorithm name and a package 58: * provider.</p> 59: * 60: * <ul> 61: * <li>If just an algorithm name is specified, the system will determine if 62: * there is an AlgorithmParameters implementation for the algorithm requested 63: * available in the environment, and if there is more than one, if there is 64: * a preferred one.</li> 65: * <li>If both an algorithm name and a package provider are specified, the 66: * system will determine if there is an implementation in the package 67: * requested, and throw an exception if there is not.</li> 68: * </ul> 69: * 70: * <p>Once an <code>AlgorithmParameters</code> object is returned, it must be 71: * initialized via a call to <code>init()</code>, using an appropriate 72: * parameter specification or parameter encoding.</p> 73: * 74: * <p>A transparent parameter specification is obtained from an 75: * <code>AlgorithmParameters</code> object via a call to 76: * <code>getParameterSpec()</code>, and a byte encoding of the parameters is 77: * obtained via a call to <code>getEncoded()</code>.</p> 78: * 79: * @author Mark Benvenuto 80: * @since 1.2 81: * @see AlgorithmParameterSpec 82: * @see java.security.spec.DSAParameterSpec 83: * @see KeyPairGenerator 84: */ 85: public class AlgorithmParameters 86: { 87: /** Service name for algorithm parameters. */ 88: private static final String ALGORITHM_PARAMETERS = "AlgorithmParameters"; 89: 90: private AlgorithmParametersSpi paramSpi; 91: private Provider provider; 92: private String algorithm; 93: 94: /** 95: * Creates an <code>AlgorithmParameters</code> object. 96: * 97: * @param paramSpi the delegate. 98: * @param provider the provider. 99: * @param algorithm the algorithm. 100: */ 101: protected AlgorithmParameters(AlgorithmParametersSpi paramSpi, 102: Provider provider, String algorithm) 103: { 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: { 116: return algorithm; 117: } 118: 119: /** 120: * <p>Generates a parameter object for the specified algorithm.</p> 121: * 122: * <p>If the default provider package provides an implementation of the 123: * requested algorithm, an instance of <code>AlgorithmParameters</code> 124: * containing that implementation is returned. If the algorithm is not 125: * available in the default package, other packages are searched.</p> 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.</p> 130: * 131: * @param algorithm the name of the algorithm requested. 132: * @return the new parameter object. 133: * @throws NoSuchAlgorithmException if the algorithm is not available in the 134: * environment. 135: */ 136: public static AlgorithmParameters getInstance(String algorithm) 137: throws NoSuchAlgorithmException 138: { 139: Provider[] p = Security.getProviders(); 140: 141: for (int i = 0; i < p.length; i++) 142: try 143: { 144: return getInstance(algorithm, p[i]); 145: } 146: catch (NoSuchAlgorithmException e) 147: { 148: // Ignore this. 149: } 150: 151: throw new NoSuchAlgorithmException(algorithm); 152: } 153: 154: /** 155: * <p>Generates a parameter object for the specified algorithm, as supplied 156: * by the specified provider, if such an algorithm is available from the 157: * provider.</p> 158: * 159: * <p>The returned parameter object must be initialized via a call to 160: * <code>init()</code>, using an appropriate parameter specification or 161: * parameter encoding.</p> 162: * 163: * @param algorithm the name of the algorithm requested. 164: * @param provider the name of the provider. 165: * @return the new parameter object. 166: * @throws NoSuchAlgorithmException if the algorithm is not available in the 167: * package supplied by the requested provider. 168: * @throws NoSuchProviderException if the provider is not available in the 169: * environment. 170: * @throws IllegalArgumentException if the provider name is null or empty. 171: * @see Provider 172: */ 173: public static AlgorithmParameters getInstance(String algorithm, String provider) 174: throws NoSuchAlgorithmException, NoSuchProviderException 175: { 176: if (provider == null || provider.length() == 0) 177: throw new IllegalArgumentException("Illegal provider"); 178: 179: Provider p = Security.getProvider(provider); 180: if (p == null) 181: throw new NoSuchProviderException(provider); 182: 183: return getInstance(algorithm, p); 184: } 185: 186: /** 187: * Generates an <code>AlgorithmParameterGenerator</code> object for the 188: * requested algorithm, as supplied from the specified provider, if such a 189: * parameter generator is available from the provider. Note: the 190: * <code>provider</code> doesn't have to be registered. 191: * 192: * @param algorithm the string name of the algorithm. 193: * @param provider the provider. 194: * @return the new <code>AlgorithmParameterGenerator</code> object. 195: * @throws NoSuchAlgorithmException if the <code>algorithm</code> is not 196: * available from the <code>provider</code>. 197: * @throws IllegalArgumentException if the <code>provider</code> is 198: * <code>null</code>. 199: * @since 1.4 200: */ 201: public static AlgorithmParameters getInstance(String algorithm, 202: Provider provider) 203: throws NoSuchAlgorithmException 204: { 205: if (provider == null) 206: throw new IllegalArgumentException("Illegal provider"); 207: 208: try 209: { 210: return new AlgorithmParameters((AlgorithmParametersSpi) 211: Engine.getInstance(ALGORITHM_PARAMETERS, algorithm, provider), 212: provider, algorithm); 213: } 214: catch (java.lang.reflect.InvocationTargetException ite) 215: { 216: throw new NoSuchAlgorithmException(algorithm); 217: } 218: catch (ClassCastException cce) 219: { 220: throw new NoSuchAlgorithmException(algorithm); 221: } 222: } 223: 224: /** 225: * Returns the provider of this parameter object. 226: * 227: * @return the provider of this parameter object. 228: */ 229: public final Provider getProvider() 230: { 231: return provider; 232: } 233: 234: /** 235: * Initializes this parameter object using the parameters specified in 236: * <code>paramSpec</code>. 237: * 238: * @param paramSpec the parameter specification. 239: * @throws InvalidParameterSpecException if the given parameter specification 240: * is inappropriate for the initialization of this parameter object, or if 241: * this parameter object has already been initialized. 242: */ 243: public final void init(AlgorithmParameterSpec paramSpec) 244: throws InvalidParameterSpecException 245: { 246: paramSpi.engineInit(paramSpec); 247: } 248: 249: /** 250: * Imports the specified parameters and decodes them according to the primary 251: * decoding format for parameters. The primary decoding format for parameters 252: * is ASN.1, if an ASN.1 specification for this type of parameters exists. 253: * 254: * @param params the encoded parameters. 255: * @throws IOException on decoding errors, or if this parameter object has 256: * already been initialized. 257: */ 258: public final void init(byte[]params) throws IOException 259: { 260: paramSpi.engineInit(params); 261: } 262: 263: /** 264: * Imports the parameters from params and decodes them according to the 265: * specified decoding scheme. If <code>format</code> is <code>null</code>, 266: * the primary decoding format for parameters is used. The primary decoding 267: * format is ASN.1, if an ASN.1 specification for these parameters exists. 268: * 269: * @param params the encoded parameters. 270: * @param format the name of the decoding scheme. 271: * @throws IOException on decoding errors, or if this parameter object has 272: * already been initialized. 273: */ 274: public final void init(byte[]params, String format) throws IOException 275: { 276: paramSpi.engineInit(params, format); 277: } 278: 279: /** 280: * Returns a (transparent) specification of this parameter object. 281: * <code>paramSpec</code> identifies the specification class in which the 282: * parameters should be returned. It could, for example, be 283: * <code>DSAParameterSpec.class</code>, to indicate that the parameters should 284: * be returned in an instance of the {@link java.security.spec.DSAParameterSpec} 285: * class. 286: * 287: * @param paramSpec the specification class in which the parameters should be 288: * returned. 289: * @return the parameter specification. 290: * @throws InvalidParameterSpecException if the requested parameter 291: * specification is inappropriate for this parameter object, or if this 292: * parameter object has not been initialized. 293: */ 294: public final AlgorithmParameterSpec getParameterSpec(Class paramSpec) 295: throws InvalidParameterSpecException 296: { 297: return paramSpi.engineGetParameterSpec(paramSpec); 298: } 299: 300: /** 301: * Returns the parameters in their primary encoding format. The primary 302: * encoding format for parameters is ASN.1, if an ASN.1 specification for 303: * this type of parameters exists. 304: * 305: * @return the parameters encoded using their primary encoding format. 306: * @throws IOException on encoding errors, or if this parameter object has not 307: * been initialized. 308: */ 309: public final byte[] getEncoded() throws IOException 310: { 311: return paramSpi.engineGetEncoded(); 312: } 313: 314: /** 315: * Returns the parameters encoded in the specified scheme. If format is 316: * <code>null</code>, the primary encoding format for parameters is used. The 317: * primary encoding format is ASN.1, if an ASN.1 specification for these 318: * parameters exists. 319: * 320: * @param format the name of the encoding format. 321: * @return the parameters encoded using the specified encoding scheme. 322: * @throws IOException on encoding errors, or if this parameter object has 323: * not been initialized. 324: */ 325: public final byte[] getEncoded(String format) throws IOException 326: { 327: return paramSpi.engineGetEncoded(format); 328: } 329: 330: /** 331: * Returns a formatted string describing the parameters. 332: * 333: * @return a formatted string describing the parameters, or <code>null</code> 334: * if this parameter object has not been initialized. 335: */ 336: public final String toString() 337: { 338: return paramSpi.engineToString(); 339: } 340: }
GNU Classpath (0.20) |