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