Source for java.security.AlgorithmParameters

   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: }