libjava/java/security/AlgorithmParameters.java

   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., 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
  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 }