Save This Page
Home » openjdk-7 » java » security » [javadoc | source]
    1   /*
    2    * Copyright (c) 1997, 2011, Oracle and/or its affiliates. All rights reserved.
    3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
    4    *
    5    * This code is free software; you can redistribute it and/or modify it
    6    * under the terms of the GNU General Public License version 2 only, as
    7    * published by the Free Software Foundation.  Oracle designates this
    8    * particular file as subject to the "Classpath" exception as provided
    9    * by Oracle in the LICENSE file that accompanied this code.
   10    *
   11    * This code is distributed in the hope that it will be useful, but WITHOUT
   12    * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
   13    * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
   14    * version 2 for more details (a copy is included in the LICENSE file that
   15    * accompanied this code).
   16    *
   17    * You should have received a copy of the GNU General Public License version
   18    * 2 along with this work; if not, write to the Free Software Foundation,
   19    * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
   20    *
   21    * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
   22    * or visit www.oracle.com if you need additional information or have any
   23    * questions.
   24    */
   25   
   26   package java.security;
   27   
   28   import java.security.spec.AlgorithmParameterSpec;
   29   
   30   /**
   31    * The <code>AlgorithmParameterGenerator</code> class is used to generate a
   32    * set of
   33    * parameters to be used with a certain algorithm. Parameter generators
   34    * are constructed using the <code>getInstance</code> factory methods
   35    * (static methods that return instances of a given class).
   36    *
   37    * <P>The object that will generate the parameters can be initialized
   38    * in two different ways: in an algorithm-independent manner, or in an
   39    * algorithm-specific manner:
   40    *
   41    * <ul>
   42    * <li>The algorithm-independent approach uses the fact that all parameter
   43    * generators share the concept of a "size" and a
   44    * source of randomness. The measure of size is universally shared
   45    * by all algorithm parameters, though it is interpreted differently
   46    * for different algorithms. For example, in the case of parameters for
   47    * the <i>DSA</i> algorithm, "size" corresponds to the size
   48    * of the prime modulus (in bits).
   49    * When using this approach, algorithm-specific parameter generation
   50    * values - if any - default to some standard values, unless they can be
   51    * derived from the specified size.<P>
   52    *
   53    * <li>The other approach initializes a parameter generator object
   54    * using algorithm-specific semantics, which are represented by a set of
   55    * algorithm-specific parameter generation values. To generate
   56    * Diffie-Hellman system parameters, for example, the parameter generation
   57    * values usually
   58    * consist of the size of the prime modulus and the size of the
   59    * random exponent, both specified in number of bits.
   60    * </ul>
   61    *
   62    * <P>In case the client does not explicitly initialize the
   63    * AlgorithmParameterGenerator
   64    * (via a call to an <code>init</code> method), each provider must supply (and
   65    * document) a default initialization. For example, the Sun provider uses a
   66    * default modulus prime size of 1024 bits for the generation of DSA
   67    * parameters.
   68    *
   69    * <p> Every implementation of the Java platform is required to support the
   70    * following standard <code>AlgorithmParameterGenerator</code> algorithms and
   71    * keysizes in parentheses:
   72    * <ul>
   73    * <li><tt>DiffieHellman</tt> (1024)</li>
   74    * <li><tt>DSA</tt> (1024)</li>
   75    * </ul>
   76    * These algorithms are described in the <a href=
   77    * "{@docRoot}/../technotes/guides/security/StandardNames.html#AlgorithmParameterGenerator">
   78    * AlgorithmParameterGenerator section</a> of the
   79    * Java Cryptography Architecture Standard Algorithm Name Documentation.
   80    * Consult the release documentation for your implementation to see if any
   81    * other algorithms are supported.
   82    *
   83    * @author Jan Luehe
   84    *
   85    *
   86    * @see AlgorithmParameters
   87    * @see java.security.spec.AlgorithmParameterSpec
   88    *
   89    * @since 1.2
   90    */
   91   
   92   public class AlgorithmParameterGenerator {
   93   
   94       // The provider
   95       private Provider provider;
   96   
   97       // The provider implementation (delegate)
   98       private AlgorithmParameterGeneratorSpi paramGenSpi;
   99   
  100       // The algorithm
  101       private String algorithm;
  102   
  103       /**
  104        * Creates an AlgorithmParameterGenerator object.
  105        *
  106        * @param paramGenSpi the delegate
  107        * @param provider the provider
  108        * @param algorithm the algorithm
  109        */
  110       protected AlgorithmParameterGenerator
  111       (AlgorithmParameterGeneratorSpi paramGenSpi, Provider provider,
  112        String algorithm) {
  113           this.paramGenSpi = paramGenSpi;
  114           this.provider = provider;
  115           this.algorithm = algorithm;
  116       }
  117   
  118       /**
  119        * Returns the standard name of the algorithm this parameter
  120        * generator is associated with.
  121        *
  122        * @return the string name of the algorithm.
  123        */
  124       public final String getAlgorithm() {
  125           return this.algorithm;
  126       }
  127   
  128       /**
  129        * Returns an AlgorithmParameterGenerator object for generating
  130        * a set of parameters to be used with the specified algorithm.
  131        *
  132        * <p> This method traverses the list of registered security Providers,
  133        * starting with the most preferred Provider.
  134        * A new AlgorithmParameterGenerator object encapsulating the
  135        * AlgorithmParameterGeneratorSpi implementation from the first
  136        * Provider that supports the specified algorithm is returned.
  137        *
  138        * <p> Note that the list of registered providers may be retrieved via
  139        * the {@link Security#getProviders() Security.getProviders()} method.
  140        *
  141        * @param algorithm the name of the algorithm this
  142        * parameter generator is associated with.
  143        * See the AlgorithmParameterGenerator section in the <a href=
  144        * "{@docRoot}/../technotes/guides/security/StandardNames.html#AlgorithmParameterGenerator">
  145        * Java Cryptography Architecture Standard Algorithm Name Documentation</a>
  146        * for information about standard algorithm names.
  147        *
  148        * @return the new AlgorithmParameterGenerator object.
  149        *
  150        * @exception NoSuchAlgorithmException if no Provider supports an
  151        *          AlgorithmParameterGeneratorSpi implementation for the
  152        *          specified algorithm.
  153        *
  154        * @see Provider
  155        */
  156       public static AlgorithmParameterGenerator getInstance(String algorithm)
  157           throws NoSuchAlgorithmException {
  158               try {
  159                   Object[] objs = Security.getImpl(algorithm,
  160                                                    "AlgorithmParameterGenerator",
  161                                                    (String)null);
  162                   return new AlgorithmParameterGenerator
  163                       ((AlgorithmParameterGeneratorSpi)objs[0],
  164                        (Provider)objs[1],
  165                        algorithm);
  166               } catch(NoSuchProviderException e) {
  167                   throw new NoSuchAlgorithmException(algorithm + " not found");
  168               }
  169       }
  170   
  171       /**
  172        * Returns an AlgorithmParameterGenerator object for generating
  173        * a set of parameters to be used with the specified algorithm.
  174        *
  175        * <p> A new AlgorithmParameterGenerator object encapsulating the
  176        * AlgorithmParameterGeneratorSpi implementation from the specified provider
  177        * is returned.  The specified provider must be registered
  178        * in the security provider list.
  179        *
  180        * <p> Note that the list of registered providers may be retrieved via
  181        * the {@link Security#getProviders() Security.getProviders()} method.
  182        *
  183        * @param algorithm the name of the algorithm this
  184        * parameter generator is associated with.
  185        * See the AlgorithmParameterGenerator section in the <a href=
  186        * "{@docRoot}/../technotes/guides/security/StandardNames.html#AlgorithmParameterGenerator">
  187        * Java Cryptography Architecture Standard Algorithm Name Documentation</a>
  188        * for information about standard algorithm names.
  189        *
  190        * @param provider the string name of the Provider.
  191        *
  192        * @return the new AlgorithmParameterGenerator object.
  193        *
  194        * @exception NoSuchAlgorithmException if an AlgorithmParameterGeneratorSpi
  195        *          implementation for the specified algorithm is not
  196        *          available from the specified provider.
  197        *
  198        * @exception NoSuchProviderException if the specified provider is not
  199        *          registered in the security provider list.
  200        *
  201        * @exception IllegalArgumentException if the provider name is null
  202        *          or empty.
  203        *
  204        * @see Provider
  205        */
  206       public static AlgorithmParameterGenerator getInstance(String algorithm,
  207                                                             String provider)
  208           throws NoSuchAlgorithmException, NoSuchProviderException
  209       {
  210           if (provider == null || provider.length() == 0)
  211               throw new IllegalArgumentException("missing provider");
  212           Object[] objs = Security.getImpl(algorithm,
  213                                            "AlgorithmParameterGenerator",
  214                                            provider);
  215           return new AlgorithmParameterGenerator
  216               ((AlgorithmParameterGeneratorSpi)objs[0], (Provider)objs[1],
  217                algorithm);
  218       }
  219   
  220       /**
  221        * Returns an AlgorithmParameterGenerator object for generating
  222        * a set of parameters to be used with the specified algorithm.
  223        *
  224        * <p> A new AlgorithmParameterGenerator object encapsulating the
  225        * AlgorithmParameterGeneratorSpi implementation from the specified Provider
  226        * object is returned.  Note that the specified Provider object
  227        * does not have to be registered in the provider list.
  228        *
  229        * @param algorithm the string name of the algorithm this
  230        * parameter generator is associated with.
  231        * See the AlgorithmParameterGenerator section in the <a href=
  232        * "{@docRoot}/../technotes/guides/security/StandardNames.html#AlgorithmParameterGenerator">
  233        * Java Cryptography Architecture Standard Algorithm Name Documentation</a>
  234        * for information about standard algorithm names.
  235        *
  236        * @param provider the Provider object.
  237        *
  238        * @return the new AlgorithmParameterGenerator object.
  239        *
  240        * @exception NoSuchAlgorithmException if an AlgorithmParameterGeneratorSpi
  241        *          implementation for the specified algorithm is not available
  242        *          from the specified Provider object.
  243        *
  244        * @exception IllegalArgumentException if the specified provider is null.
  245        *
  246        * @see Provider
  247        *
  248        * @since 1.4
  249        */
  250       public static AlgorithmParameterGenerator getInstance(String algorithm,
  251                                                             Provider provider)
  252           throws NoSuchAlgorithmException
  253       {
  254           if (provider == null)
  255               throw new IllegalArgumentException("missing provider");
  256           Object[] objs = Security.getImpl(algorithm,
  257                                            "AlgorithmParameterGenerator",
  258                                            provider);
  259           return new AlgorithmParameterGenerator
  260               ((AlgorithmParameterGeneratorSpi)objs[0], (Provider)objs[1],
  261                algorithm);
  262       }
  263   
  264       /**
  265        * Returns the provider of this algorithm parameter generator object.
  266        *
  267        * @return the provider of this algorithm parameter generator object
  268        */
  269       public final Provider getProvider() {
  270           return this.provider;
  271       }
  272   
  273       /**
  274        * Initializes this parameter generator for a certain size.
  275        * To create the parameters, the <code>SecureRandom</code>
  276        * implementation of the highest-priority installed provider is used as
  277        * the source of randomness.
  278        * (If none of the installed providers supply an implementation of
  279        * <code>SecureRandom</code>, a system-provided source of randomness is
  280        * used.)
  281        *
  282        * @param size the size (number of bits).
  283        */
  284       public final void init(int size) {
  285           paramGenSpi.engineInit(size, new SecureRandom());
  286       }
  287   
  288       /**
  289        * Initializes this parameter generator for a certain size and source
  290        * of randomness.
  291        *
  292        * @param size the size (number of bits).
  293        * @param random the source of randomness.
  294        */
  295       public final void init(int size, SecureRandom random) {
  296           paramGenSpi.engineInit(size, random);
  297       }
  298   
  299       /**
  300        * Initializes this parameter generator with a set of algorithm-specific
  301        * parameter generation values.
  302        * To generate the parameters, the <code>SecureRandom</code>
  303        * implementation of the highest-priority installed provider is used as
  304        * the source of randomness.
  305        * (If none of the installed providers supply an implementation of
  306        * <code>SecureRandom</code>, a system-provided source of randomness is
  307        * used.)
  308        *
  309        * @param genParamSpec the set of algorithm-specific parameter generation values.
  310        *
  311        * @exception InvalidAlgorithmParameterException if the given parameter
  312        * generation values are inappropriate for this parameter generator.
  313        */
  314       public final void init(AlgorithmParameterSpec genParamSpec)
  315           throws InvalidAlgorithmParameterException {
  316               paramGenSpi.engineInit(genParamSpec, new SecureRandom());
  317       }
  318   
  319       /**
  320        * Initializes this parameter generator with a set of algorithm-specific
  321        * parameter generation values.
  322        *
  323        * @param genParamSpec the set of algorithm-specific parameter generation values.
  324        * @param random the source of randomness.
  325        *
  326        * @exception InvalidAlgorithmParameterException if the given parameter
  327        * generation values are inappropriate for this parameter generator.
  328        */
  329       public final void init(AlgorithmParameterSpec genParamSpec,
  330                              SecureRandom random)
  331           throws InvalidAlgorithmParameterException {
  332               paramGenSpi.engineInit(genParamSpec, random);
  333       }
  334   
  335       /**
  336        * Generates the parameters.
  337        *
  338        * @return the new AlgorithmParameters object.
  339        */
  340       public final AlgorithmParameters generateParameters() {
  341           return paramGenSpi.engineGenerateParameters();
  342       }
  343   }

Save This Page
Home » openjdk-7 » java » security » [javadoc | source]