Source for java.security.AlgorithmParameterGenerator

   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: }