gomp-20050608-branch/libjava/classpath/java/security/AlgorithmParameterGenerator.java

   1 /* AlgorithmParameterGenerator.java --- Algorithm Parameter Generator
   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.security.spec.AlgorithmParameterSpec;
  44
  45 /**
  46  * <p>The <code>AlgorithmParameterGenerator</code> class is used to generate a
  47  * set of parameters to be used with a certain algorithm. Parameter generators
  48  * are constructed using the <code>getInstance()</code> factory methods (static
  49  * methods that return instances of a given class).</p>
  50  *
  51  * <p>The object that will generate the parameters can be initialized in two
  52  * different ways: in an algorithm-independent manner, or in an
  53  * algorithm-specific manner:</p>
  54  *
  55  * <ul>
  56  *  <li>The algorithm-independent approach uses the fact that all parameter
  57  *  generators share the concept of a <i>"size"</i> and a <i>source of
  58  *  randomness</i>. The measure of <i>size</i> is universally shared by all
  59  *  algorithm parameters, though it is interpreted differently for different
  60  *  algorithms. For example, in the case of parameters for the <i>DSA</i>
  61  *  algorithm, <i>"size"</i> corresponds to the size of the prime modulus (in
  62  *  bits). When using this approach, algorithm-specific parameter generation
  63  *  values - if any - default to some standard values, unless they can be
  64  *  derived from the specified size.</li>
  65  *  <li>The other approach initializes a parameter generator object using
  66  *  algorithm-specific semantics, which are represented by a set of
  67  *  algorithm-specific parameter generation values. To generate Diffie-Hellman
  68  *  system parameters, for example, the parameter generation values usually
  69  *  consist of the size of the prime modulus and the size of the random
  70  *  exponent, both specified in number of bits.</li>
  71  * </ul>
  72  *
  73  * <p>In case the client does not explicitly initialize the
  74  * <code>AlgorithmParameterGenerator</code> (via a call to an <code>init()</code>
  75  * method), each provider must supply (and document) a default initialization.
  76  * For example, the <b>GNU</b> provider uses a default modulus prime size of
  77  * <code>1024</code> bits for the generation of <i>DSA</i> parameters.
  78  *
  79  * @author Mark Benvenuto
  80  * @since 1.2
  81  * @see AlgorithmParameters
  82  * @see AlgorithmParameterSpec
  83  */
  84 public class AlgorithmParameterGenerator
  85 {
  86   /** Service name for algorithm parameter generators. */
  87   private static final String ALGORITHM_PARAMETER_GENERATOR =
  88     "AlgorithmParameterGenerator";
  89
  90   private AlgorithmParameterGeneratorSpi paramGenSpi;
  91   private Provider provider;
  92   private String algorithm;
  93
  94   /**
  95    * Creates an <code>AlgorithmParameterGenerator</code> object.
  96    *
  97    * @param paramGenSpi the delegate.
  98    * @param provider the provider.
  99    * @param algorithm the algorithm.
 100    */
 101   protected AlgorithmParameterGenerator(AlgorithmParameterGeneratorSpi
 102                                         paramGenSpi, Provider provider,
 103                                         String algorithm)
 104   {
 105     this.paramGenSpi = paramGenSpi;
 106     this.provider = provider;
 107     this.algorithm = algorithm;
 108   }
 109
 110   /**
 111    * Returns the standard name of the algorithm this parameter generator is
 112    * associated with.
 113    *
 114    * @return the string name of the algorithm.
 115    */
 116   public final String getAlgorithm()
 117   {
 118     return algorithm;
 119   }
 120
 121   /**
 122    * Generates an <code>AlgorithmParameterGenerator</code> object that
 123    * implements the specified digest algorithm. If the default provider package
 124    * provides an implementation of the requested digest algorithm, an instance
 125    * of <code>AlgorithmParameterGenerator</code> containing that implementation
 126    * is returned. If the algorithm is not available in the default package,
 127    * other packages are searched.
 128    *
 129    * @param algorithm the string name of the algorithm this parameter generator
 130    * is associated with.
 131    * @return the new <code>AlgorithmParameterGenerator</code> object.
 132    * @throws NoSuchAlgorithmException if the algorithm is not available in the
 133    * environment.
 134    */
 135   public static AlgorithmParameterGenerator 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 e)
 145         {
 146           // Ignore.
 147         }
 148
 149     throw new NoSuchAlgorithmException(algorithm);
 150   }
 151
 152   /**
 153    * Generates an <code>AlgorithmParameterGenerator</code> object for the
 154    * requested algorithm, as supplied from the specified provider, if such a
 155    * parameter generator is available from the provider.
 156    *
 157    * @param algorithm the string name of the algorithm.
 158    * @param provider the string name of the provider.
 159    * @return the new <code>AlgorithmParameterGenerator</code> object.
 160    * @throws NoSuchAlgorithmException if the <code>algorithm</code> is not
 161    * available from the <code>provider</code>.
 162    * @throws NoSuchProviderException if the <code>provider</code> is not
 163    * available in the environment.
 164    * @throws IllegalArgumentException if the <code>provider</code> name is
 165    * <code>null</code> or empty.
 166    * @see Provider
 167    */
 168   public static AlgorithmParameterGenerator getInstance(String algorithm,
 169                                                         String provider)
 170     throws NoSuchAlgorithmException, NoSuchProviderException
 171   {
 172     if (provider == null || provider.length() == 0)
 173       throw new IllegalArgumentException("Illegal provider");
 174
 175     Provider p = Security.getProvider(provider);
 176     if (p == null)
 177       throw new NoSuchProviderException(provider);
 178
 179     return getInstance(algorithm, p);
 180   }
 181
 182   /**
 183    * Generates an AlgorithmParameterGenerator object for the requested
 184    * algorithm, as supplied from the specified provider, if such a parameter
 185    * generator is available from the provider. Note: the <code>provider</code>
 186    * doesn't have to be registered.
 187    *
 188    * @param algorithm the string name of the algorithm.
 189    * @param provider the provider.
 190    * @return the new AlgorithmParameterGenerator object.
 191    * @throws NoSuchAlgorithmException if the algorithm is not available from
 192    * the provider.
 193    * @throws IllegalArgumentException if the provider is null.
 194    * @since 1.4
 195    * @see Provider
 196    */
 197   public static AlgorithmParameterGenerator getInstance(String algorithm,
 198                                                         Provider provider)
 199     throws NoSuchAlgorithmException
 200   {
 201     if (provider == null)
 202       throw new IllegalArgumentException("Illegal provider");
 203
 204     try
 205       {
 206         return new AlgorithmParameterGenerator(
 207           (AlgorithmParameterGeneratorSpi) Engine.getInstance(
 208             ALGORITHM_PARAMETER_GENERATOR, algorithm, provider),
 209           provider, algorithm);
 210       }
 211     catch (java.lang.reflect.InvocationTargetException ite)
 212       {
 213         throw new NoSuchAlgorithmException(algorithm);
 214       }
 215     catch (ClassCastException cce)
 216       {
 217         throw new NoSuchAlgorithmException(algorithm);
 218       }
 219   }
 220
 221   /**
 222    * Returns the provider of this algorithm parameter generator object.
 223    *
 224    * @return the provider of this algorithm parameter generator object.
 225    */
 226   public final Provider getProvider()
 227   {
 228     return provider;
 229   }
 230
 231   /**
 232    * Initializes this parameter generator for a certain <i>size</i>. To create
 233    * the parameters, the {@link SecureRandom} implementation of the
 234    * highest-priority installed provider is used as the source of randomness.
 235    * (If none of the installed providers supply an implementation of
 236    * {@link SecureRandom}, a system-provided source of randomness is used.)
 237    *
 238    * @param size the size (number of bits).
 239    */
 240   public final void init(int size)
 241   {
 242     init(size, new SecureRandom());
 243   }
 244
 245   /**
 246    * Initializes this parameter generator for a certain size and source of
 247    * randomness.
 248    *
 249    * @param size the size (number of bits).
 250    * @param random the source of randomness.
 251    */
 252   public final void init(int size, SecureRandom random)
 253   {
 254     paramGenSpi.engineInit(size, random);
 255   }
 256
 257   /**
 258    * Initializes this parameter generator with a set of algorithm-specific
 259    * parameter generation values. To generate the parameters, the {@link
 260    * SecureRandom} implementation of the highest-priority installed provider is
 261    * used as the source of randomness. (If none of the installed providers
 262    * supply an implementation of {@link SecureRandom}, a system-provided source
 263    * of randomness is used.)
 264    *
 265    * @param genParamSpec the set of algorithm-specific parameter generation
 266    * values.
 267    * @throws InvalidAlgorithmParameterException if the given parameter
 268    * generation values are inappropriate for this parameter generator.
 269    */
 270   public final void init(AlgorithmParameterSpec genParamSpec)
 271     throws InvalidAlgorithmParameterException
 272   {
 273     init(genParamSpec, new SecureRandom());
 274   }
 275
 276   /**
 277    * Initializes this parameter generator with a set of algorithm-specific
 278    * parameter generation values.
 279    *
 280    * @param genParamSpec the set of algorithm-specific parameter generation
 281    * values.
 282    * @param random the source of randomness.
 283    * @throws InvalidAlgorithmParameterException if the given parameter
 284    * generation values are inappropriate for this parameter generator.
 285    */
 286   public final void init(AlgorithmParameterSpec genParamSpec,
 287                          SecureRandom random)
 288     throws InvalidAlgorithmParameterException
 289   {
 290     paramGenSpi.engineInit(genParamSpec, random);
 291   }
 292
 293   /**
 294    * Generates the parameters.
 295    *
 296    * @return the new {@link AlgorithmParameters} object.
 297    */
 298   public final AlgorithmParameters generateParameters()
 299   {
 300     return paramGenSpi.engineGenerateParameters();
 301   }
 302 }