libjava/java/security/AlgorithmParameterGenerator.java

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