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