libjava/java/security/AlgorithmParameters.java

   1 /* AlgorithmParameters.java --- Algorithm Parameters Implementation Class
   2    Copyright (C) 1999, 2003 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., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 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 package java.security;
  39
  40 import java.security.spec.InvalidParameterSpecException;
  41 import java.security.spec.AlgorithmParameterSpec;
  42 import java.io.IOException;
  43
  44 /**
  45  * <p>This class is used as an opaque representation of cryptographic
  46  * parameters.</p>
  47  *
  48  * <p>An <code>AlgorithmParameters</code> object for managing the parameters
  49  * for a particular algorithm can be obtained by calling one of the
  50  * <code>getInstance()</code> factory methods (static methods that return
  51  * instances of a given class).</p>
  52  *
  53  * <p>There are two ways to request such an implementation: by specifying
  54  * either just an algorithm name, or both an algorithm name and a package
  55  * provider.</p>
  56  *
  57  * <ul>
  58  *    <li>If just an algorithm name is specified, the system will determine if
  59  *    there is an AlgorithmParameters implementation for the algorithm requested
  60  *    available in the environment, and if there is more than one, if there is
  61  *    a preferred one.</li>
  62  *    <li>If both an algorithm name and a package provider are specified, the
  63  *    system will determine if there is an implementation in the package
  64  *    requested, and throw an exception if there is not.</li>
  65  * </ul>
  66  *
  67  * <p>Once an <code>AlgorithmParameters</code> object is returned, it must be
  68  * initialized via a call to <code>init()</code>, using an appropriate
  69  * parameter specification or parameter encoding.</p>
  70  *
  71  * <p>A transparent parameter specification is obtained from an
  72  * <ocde>AlgorithmParameters</code> object via a call to
  73  * <code>getParameterSpec()</code>, and a byte encoding of the parameters is
  74  * obtained via a call to <code>getEncoded()</code>.</p>
  75  *
  76  * @author Mark Benvenuto
  77  * @since 1.2
  78  * @see AlgorithmParameterSpec
  79  * @see java.security.spec.DSAParameterSpec
  80  * @see KeyPairGenerator
  81  */
  82 public class AlgorithmParameters
  83 {
  84   /** Service name for algorithm parameters. */
  85   private static final String ALGORITHM_PARAMETERS = "AlgorithmParameters";
  86
  87   private AlgorithmParametersSpi paramSpi;
  88   private Provider provider;
  89   private String algorithm;
  90
  91   /**
  92    * Creates an <code>AlgorithmParameters</code> object.
  93    *
  94    * @param paramSpi the delegate.
  95    * @param provider the provider.
  96    * @param algorithm the algorithm.
  97    */
  98   protected AlgorithmParameters(AlgorithmParametersSpi paramSpi,
  99                                 Provider provider, String algorithm)
 100   {
 101     this.paramSpi = paramSpi;
 102     this.provider = provider;
 103     this.algorithm = algorithm;
 104   }
 105
 106   /**
 107    * Returns the name of the algorithm associated with this parameter object.
 108    *
 109    * @return the algorithm name.
 110    */
 111   public final String getAlgorithm()
 112   {
 113     return algorithm;
 114   }
 115
 116   /**
 117    * <p>Generates a parameter object for the specified algorithm.</p>
 118    *
 119    * <p>If the default provider package provides an implementation of the
 120    * requested algorithm, an instance of <code>AlgorithmParameters</code>
 121    * containing that implementation is returned. If the algorithm is not
 122    * available in the default package, other packages are searched.</p>
 123    *
 124    * <p>The returned parameter object must be initialized via a call to
 125    * <code>init()</code>, using an appropriate parameter specification or
 126    * parameter encoding.</p>
 127    *
 128    * @param algorithm the name of the algorithm requested.
 129    * @return the new parameter object.
 130    * @throws NoSuchAlgorithmException if the algorithm is not available in the
 131    * environment.
 132    */
 133   public static AlgorithmParameters getInstance(String algorithm)
 134     throws NoSuchAlgorithmException
 135   {
 136     Provider[] p = Security.getProviders();
 137     for (int i = 0; i < p.length; i++)
 138       try
 139         {
 140           return getInstance(algorithm, p[i]);
 141         }
 142       catch (NoSuchAlgorithmException ignored) {}
 143
 144     throw new NoSuchAlgorithmException(algorithm);
 145   }
 146
 147   /**
 148    * <p>Generates a parameter object for the specified algorithm, as supplied
 149    * by the specified provider, if such an algorithm is available from the
 150    * provider.</p>
 151    *
 152    * <p>The returned parameter object must be initialized via a call to
 153    * <code>init()</code>, using an appropriate parameter specification or
 154    * parameter encoding.</p>
 155    *
 156    * @param algorithm the name of the algorithm requested.
 157    * @param provider the name of the provider.
 158    * @return the new parameter object.
 159    * @throws NoSuchAlgorithmException if the algorithm is not available in the
 160    * package supplied by the requested provider.
 161    * @throws NoSuchProviderException if the provider is not available in the
 162    * environment.
 163    * @throws IllegalArgumentException if the provider name is null or empty.
 164    * @see Provider
 165    */
 166   public static AlgorithmParameters getInstance(String algorithm, String provider)
 167     throws NoSuchAlgorithmException, NoSuchProviderException
 168   {
 169     if (provider == null || provider.length() == 0)
 170       throw new IllegalArgumentException("Illegal provider");
 171
 172     Provider p = Security.getProvider(provider);
 173     if (p == null)
 174       throw new NoSuchProviderException();
 175
 176     return getInstance(algorithm, p);
 177   }
 178
 179   /**
 180    * Generates an <code>AlgorithmParameterGenerator</code> object for the
 181    * requested algorithm, as supplied from the specified provider, if such a
 182    * parameter generator is available from the provider. Note: the
 183    * <code>provider</code> doesn't have to be registered.
 184    *
 185    * @param algorithm the string name of the algorithm.
 186    * @param provider the provider.
 187    * @return the new <code>AlgorithmParameterGenerator</code> object.
 188    * @throws NoSuchAlgorithmException if the <code>algorithm</code> is not
 189    * available from the <code>provider</code>.
 190    * @throws IllegalArgumentException if the <code>provider</code> is
 191    * <code>null</code>.
 192    * @since 1.4
 193    */
 194   public static AlgorithmParameters getInstance(String algorithm,
 195                                                 Provider provider)
 196     throws NoSuchAlgorithmException
 197   {
 198     if (provider == null)
 199       throw new IllegalArgumentException("Illegal provider");
 200
 201     try
 202       {
 203         return new AlgorithmParameters((AlgorithmParametersSpi)
 204           Engine.getInstance(ALGORITHM_PARAMETERS, algorithm, provider),
 205           provider, algorithm);
 206       }
 207     catch (ClassCastException cce)
 208       {
 209         throw new NoSuchAlgorithmException(algorithm);
 210       }
 211   }
 212
 213   /**
 214    * Returns the provider of this parameter object.
 215    *
 216    * @return the provider of this parameter object.
 217    */
 218   public final Provider getProvider()
 219   {
 220     return provider;
 221   }
 222
 223   /**
 224    * Initializes this parameter object using the parameters specified in
 225    * <code>paramSpec</code>.
 226    *
 227    * @param paramSpec the parameter specification.
 228    * @throws InvalidParameterSpecException if the given parameter specification
 229    * is inappropriate for the initialization of this parameter object, or if
 230    * this parameter object has already been initialized.
 231    */
 232   public final void init(AlgorithmParameterSpec paramSpec)
 233     throws InvalidParameterSpecException
 234   {
 235     paramSpi.engineInit(paramSpec);
 236   }
 237
 238   /**
 239    * Imports the specified parameters and decodes them according to the primary
 240    * decoding format for parameters. The primary decoding format for parameters
 241    * is ASN.1, if an ASN.1 specification for this type of parameters exists.
 242    *
 243    * @param params the encoded parameters.
 244    * @throws IOException on decoding errors, or if this parameter object has
 245    * already been initialized.
 246    */
 247   public final void init(byte[]params) throws IOException
 248   {
 249     paramSpi.engineInit(params);
 250   }
 251
 252   /**
 253    * Imports the parameters from params and decodes them according to the
 254    * specified decoding scheme. If <code>format</code> is <code>null</code>,
 255    * the primary decoding format for parameters is used. The primary decoding
 256    * format is ASN.1, if an ASN.1 specification for these parameters exists.
 257    *
 258    * @param params the encoded parameters.
 259    * @param format the name of the decoding scheme.
 260    * @throws IOException on decoding errors, or if this parameter object has
 261    * already been initialized.
 262    */
 263   public final void init(byte[]params, String format) throws IOException
 264   {
 265     paramSpi.engineInit(params, format);
 266   }
 267
 268   /**
 269    * Returns a (transparent) specification of this parameter object.
 270    * <code>paramSpec</code> identifies the specification class in which the
 271    * parameters should be returned. It could, for example, be
 272    * <code>DSAParameterSpec.class</code>, to indicate that the parameters should
 273    * be returned in an instance of the {@link java.security.spec.DSAParameterSpec}
 274    * class.
 275    *
 276    * @param paramSpec the specification class in which the parameters should be
 277    * returned.
 278    * @return the parameter specification.
 279    * @throws InvalidParameterSpecException if the requested parameter
 280    * specification is inappropriate for this parameter object, or if this
 281    * parameter object has not been initialized.
 282    */
 283   public final AlgorithmParameterSpec getParameterSpec(Class paramSpec)
 284     throws InvalidParameterSpecException
 285   {
 286     return paramSpi.engineGetParameterSpec(paramSpec);
 287   }
 288
 289   /**
 290    * Returns the parameters in their primary encoding format. The primary
 291    * encoding format for parameters is ASN.1, if an ASN.1 specification for
 292    * this type of parameters exists.
 293    *
 294    * @return the parameters encoded using their primary encoding format.
 295    * @throws IOException on encoding errors, or if this parameter object has not
 296    * been initialized.
 297    */
 298   public final byte[] getEncoded() throws IOException
 299   {
 300     return paramSpi.engineGetEncoded();
 301   }
 302
 303   /**
 304    * Returns the parameters encoded in the specified scheme. If format is
 305    * <code>null</code>, the primary encoding format for parameters is used. The
 306    * primary encoding format is ASN.1, if an ASN.1 specification for these
 307    * parameters exists.
 308    *
 309    * @param format the name of the encoding format.
 310    * @return the parameters encoded using the specified encoding scheme.
 311    * @throws IOException on encoding errors, or if this parameter object has
 312    * not been initialized.
 313    */
 314   public final byte[] getEncoded(String format) throws IOException
 315   {
 316     return paramSpi.engineGetEncoded(format);
 317   }
 318
 319   /**
 320    * Returns a formatted string describing the parameters.
 321    *
 322    * @return a formatted string describing the parameters, or <code>null</code>
 323    * if this parameter object has not been initialized.
 324    */
 325   public final String toString()
 326   {
 327     return paramSpi.engineToString();
 328   }
 329 }