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.io;
   29   import java.security.spec.AlgorithmParameterSpec;
   30   import java.security.spec.InvalidParameterSpecException;
   31   
   32   /**
   33    * This class is used as an opaque representation of cryptographic parameters.
   34    *
   35    * <p>An <code>AlgorithmParameters</code> object for managing the parameters
   36    * for a particular algorithm can be obtained by
   37    * calling one of the <code>getInstance</code> factory methods
   38    * (static methods that return instances of a given class).
   39    *
   40    * <p>Once an <code>AlgorithmParameters</code> object is obtained, it must be
   41    * initialized via a call to <code>init</code>, using an appropriate parameter
   42    * specification or parameter encoding.
   43    *
   44    * <p>A transparent parameter specification is obtained from an
   45    * <code>AlgorithmParameters</code> object via a call to
   46    * <code>getParameterSpec</code>, and a byte encoding of the parameters is
   47    * obtained via a call to <code>getEncoded</code>.
   48    *
   49    * <p> Every implementation of the Java platform is required to support the
   50    * following standard <code>AlgorithmParameters</code> algorithms:
   51    * <ul>
   52    * <li><tt>AES</tt></li>
   53    * <li><tt>DES</tt></li>
   54    * <li><tt>DESede</tt></li>
   55    * <li><tt>DiffieHellman</tt></li>
   56    * <li><tt>DSA</tt></li>
   57    * </ul>
   58    * These algorithms are described in the <a href=
   59    * "{@docRoot}/../technotes/guides/security/StandardNames.html#AlgorithmParameters">
   60    * AlgorithmParameters section</a> of the
   61    * Java Cryptography Architecture Standard Algorithm Name Documentation.
   62    * Consult the release documentation for your implementation to see if any
   63    * other algorithms are supported.
   64    *
   65    * @author Jan Luehe
   66    *
   67    *
   68    * @see java.security.spec.AlgorithmParameterSpec
   69    * @see java.security.spec.DSAParameterSpec
   70    * @see KeyPairGenerator
   71    *
   72    * @since 1.2
   73    */
   74   
   75   public class AlgorithmParameters {
   76   
   77       // The provider
   78       private Provider provider;
   79   
   80       // The provider implementation (delegate)
   81       private AlgorithmParametersSpi paramSpi;
   82   
   83       // The algorithm
   84       private String algorithm;
   85   
   86       // Has this object been initialized?
   87       private boolean initialized = false;
   88   
   89       /**
   90        * Creates an AlgorithmParameters object.
   91        *
   92        * @param paramSpi the delegate
   93        * @param provider the provider
   94        * @param algorithm the algorithm
   95        */
   96       protected AlgorithmParameters(AlgorithmParametersSpi paramSpi,
   97                                     Provider provider, String algorithm)
   98       {
   99           this.paramSpi = paramSpi;
  100           this.provider = provider;
  101           this.algorithm = algorithm;
  102       }
  103   
  104       /**
  105        * Returns the name of the algorithm associated with this parameter object.
  106        *
  107        * @return the algorithm name.
  108        */
  109       public final String getAlgorithm() {
  110           return this.algorithm;
  111       }
  112   
  113       /**
  114        * Returns a parameter object for the specified algorithm.
  115        *
  116        * <p> This method traverses the list of registered security Providers,
  117        * starting with the most preferred Provider.
  118        * A new AlgorithmParameters object encapsulating the
  119        * AlgorithmParametersSpi implementation from the first
  120        * Provider that supports the specified algorithm is returned.
  121        *
  122        * <p> Note that the list of registered providers may be retrieved via
  123        * the {@link Security#getProviders() Security.getProviders()} method.
  124        *
  125        * <p> The returned parameter object must be initialized via a call to
  126        * <code>init</code>, using an appropriate parameter specification or
  127        * parameter encoding.
  128        *
  129        * @param algorithm the name of the algorithm requested.
  130        * See the AlgorithmParameters section in the <a href=
  131        * "{@docRoot}/../technotes/guides/security/StandardNames.html#AlgorithmParameters">
  132        * Java Cryptography Architecture Standard Algorithm Name Documentation</a>
  133        * for information about standard algorithm names.
  134        *
  135        * @return the new parameter object.
  136        *
  137        * @exception NoSuchAlgorithmException if no Provider supports an
  138        *          AlgorithmParametersSpi implementation for the
  139        *          specified algorithm.
  140        *
  141        * @see Provider
  142        */
  143       public static AlgorithmParameters getInstance(String algorithm)
  144       throws NoSuchAlgorithmException {
  145           try {
  146               Object[] objs = Security.getImpl(algorithm, "AlgorithmParameters",
  147                                                (String)null);
  148               return new AlgorithmParameters((AlgorithmParametersSpi)objs[0],
  149                                              (Provider)objs[1],
  150                                              algorithm);
  151           } catch(NoSuchProviderException e) {
  152               throw new NoSuchAlgorithmException(algorithm + " not found");
  153           }
  154       }
  155   
  156       /**
  157        * Returns a parameter object for the specified algorithm.
  158        *
  159        * <p> A new AlgorithmParameters object encapsulating the
  160        * AlgorithmParametersSpi implementation from the specified provider
  161        * is returned.  The specified provider must be registered
  162        * in the security provider list.
  163        *
  164        * <p> Note that the list of registered providers may be retrieved via
  165        * the {@link Security#getProviders() Security.getProviders()} method.
  166        *
  167        * <p>The returned parameter object must be initialized via a call to
  168        * <code>init</code>, using an appropriate parameter specification or
  169        * parameter encoding.
  170        *
  171        * @param algorithm the name of the algorithm requested.
  172        * See the AlgorithmParameters section in the <a href=
  173        * "{@docRoot}/../technotes/guides/security/StandardNames.html#AlgorithmParameters">
  174        * Java Cryptography Architecture Standard Algorithm Name Documentation</a>
  175        * for information about standard algorithm names.
  176        *
  177        * @param provider the name of the provider.
  178        *
  179        * @return the new parameter object.
  180        *
  181        * @exception NoSuchAlgorithmException if an AlgorithmParametersSpi
  182        *          implementation for the specified algorithm is not
  183        *          available from the specified provider.
  184        *
  185        * @exception NoSuchProviderException if the specified provider is not
  186        *          registered in the security provider list.
  187        *
  188        * @exception IllegalArgumentException if the provider name is null
  189        *          or empty.
  190        *
  191        * @see Provider
  192        */
  193       public static AlgorithmParameters getInstance(String algorithm,
  194                                                     String provider)
  195           throws NoSuchAlgorithmException, NoSuchProviderException
  196       {
  197           if (provider == null || provider.length() == 0)
  198               throw new IllegalArgumentException("missing provider");
  199           Object[] objs = Security.getImpl(algorithm, "AlgorithmParameters",
  200                                            provider);
  201           return new AlgorithmParameters((AlgorithmParametersSpi)objs[0],
  202                                          (Provider)objs[1],
  203                                          algorithm);
  204       }
  205   
  206       /**
  207        * Returns a parameter object for the specified algorithm.
  208        *
  209        * <p> A new AlgorithmParameters object encapsulating the
  210        * AlgorithmParametersSpi implementation from the specified Provider
  211        * object is returned.  Note that the specified Provider object
  212        * does not have to be registered in the provider list.
  213        *
  214        * <p>The returned parameter object must be initialized via a call to
  215        * <code>init</code>, using an appropriate parameter specification or
  216        * parameter encoding.
  217        *
  218        * @param algorithm the name of the algorithm requested.
  219        * See the AlgorithmParameters section in the <a href=
  220        * "{@docRoot}/../technotes/guides/security/StandardNames.html#AlgorithmParameters">
  221        * Java Cryptography Architecture Standard Algorithm Name Documentation</a>
  222        * for information about standard algorithm names.
  223        *
  224        * @param provider the name of the provider.
  225        *
  226        * @return the new parameter object.
  227        *
  228        * @exception NoSuchAlgorithmException if an AlgorithmParameterGeneratorSpi
  229        *          implementation for the specified algorithm is not available
  230        *          from the specified Provider object.
  231        *
  232        * @exception IllegalArgumentException if the provider is null.
  233        *
  234        * @see Provider
  235        *
  236        * @since 1.4
  237        */
  238       public static AlgorithmParameters getInstance(String algorithm,
  239                                                     Provider provider)
  240           throws NoSuchAlgorithmException
  241       {
  242           if (provider == null)
  243               throw new IllegalArgumentException("missing provider");
  244           Object[] objs = Security.getImpl(algorithm, "AlgorithmParameters",
  245                                            provider);
  246           return new AlgorithmParameters((AlgorithmParametersSpi)objs[0],
  247                                          (Provider)objs[1],
  248                                          algorithm);
  249       }
  250   
  251       /**
  252        * Returns the provider of this parameter object.
  253        *
  254        * @return the provider of this parameter object
  255        */
  256       public final Provider getProvider() {
  257           return this.provider;
  258       }
  259   
  260       /**
  261        * Initializes this parameter object using the parameters
  262        * specified in <code>paramSpec</code>.
  263        *
  264        * @param paramSpec the parameter specification.
  265        *
  266        * @exception InvalidParameterSpecException if the given parameter
  267        * specification is inappropriate for the initialization of this parameter
  268        * object, or if this parameter object has already been initialized.
  269        */
  270       public final void init(AlgorithmParameterSpec paramSpec)
  271           throws InvalidParameterSpecException
  272       {
  273           if (this.initialized)
  274               throw new InvalidParameterSpecException("already initialized");
  275           paramSpi.engineInit(paramSpec);
  276           this.initialized = true;
  277       }
  278   
  279       /**
  280        * Imports the specified parameters and decodes them according to the
  281        * primary decoding format for parameters. The primary decoding
  282        * format for parameters is ASN.1, if an ASN.1 specification for this type
  283        * of parameters exists.
  284        *
  285        * @param params the encoded parameters.
  286        *
  287        * @exception IOException on decoding errors, or if this parameter object
  288        * has already been initialized.
  289        */
  290       public final void init(byte[] params) throws IOException {
  291           if (this.initialized)
  292               throw new IOException("already initialized");
  293           paramSpi.engineInit(params);
  294           this.initialized = true;
  295       }
  296   
  297       /**
  298        * Imports the parameters from <code>params</code> and decodes them
  299        * according to the specified decoding scheme.
  300        * If <code>format</code> is null, the
  301        * primary decoding format for parameters is used. The primary decoding
  302        * format is ASN.1, if an ASN.1 specification for these parameters
  303        * exists.
  304        *
  305        * @param params the encoded parameters.
  306        *
  307        * @param format the name of the decoding scheme.
  308        *
  309        * @exception IOException on decoding errors, or if this parameter object
  310        * has already been initialized.
  311        */
  312       public final void init(byte[] params, String format) throws IOException {
  313           if (this.initialized)
  314               throw new IOException("already initialized");
  315           paramSpi.engineInit(params, format);
  316           this.initialized = true;
  317       }
  318   
  319       /**
  320        * Returns a (transparent) specification of this parameter object.
  321        * <code>paramSpec</code> identifies the specification class in which
  322        * the parameters should be returned. It could, for example, be
  323        * <code>DSAParameterSpec.class</code>, to indicate that the
  324        * parameters should be returned in an instance of the
  325        * <code>DSAParameterSpec</code> class.
  326        *
  327        * @param paramSpec the specification class in which
  328        * the parameters should be returned.
  329        *
  330        * @return the parameter specification.
  331        *
  332        * @exception InvalidParameterSpecException if the requested parameter
  333        * specification is inappropriate for this parameter object, or if this
  334        * parameter object has not been initialized.
  335        */
  336       public final <T extends AlgorithmParameterSpec>
  337           T getParameterSpec(Class<T> paramSpec)
  338           throws InvalidParameterSpecException
  339       {
  340           if (this.initialized == false) {
  341               throw new InvalidParameterSpecException("not initialized");
  342           }
  343           return paramSpi.engineGetParameterSpec(paramSpec);
  344       }
  345   
  346       /**
  347        * Returns the parameters in their primary encoding format.
  348        * The primary encoding format for parameters is ASN.1, if an ASN.1
  349        * specification for this type of parameters exists.
  350        *
  351        * @return the parameters encoded using their primary encoding format.
  352        *
  353        * @exception IOException on encoding errors, or if this parameter object
  354        * has not been initialized.
  355        */
  356       public final byte[] getEncoded() throws IOException
  357       {
  358           if (this.initialized == false) {
  359               throw new IOException("not initialized");
  360           }
  361           return paramSpi.engineGetEncoded();
  362       }
  363   
  364       /**
  365        * Returns the parameters encoded in the specified scheme.
  366        * If <code>format</code> is null, the
  367        * primary encoding format for parameters is used. The primary encoding
  368        * format is ASN.1, if an ASN.1 specification for these parameters
  369        * exists.
  370        *
  371        * @param format the name of the encoding format.
  372        *
  373        * @return the parameters encoded using the specified encoding scheme.
  374        *
  375        * @exception IOException on encoding errors, or if this parameter object
  376        * has not been initialized.
  377        */
  378       public final byte[] getEncoded(String format) throws IOException
  379       {
  380           if (this.initialized == false) {
  381               throw new IOException("not initialized");
  382           }
  383           return paramSpi.engineGetEncoded(format);
  384       }
  385   
  386       /**
  387        * Returns a formatted string describing the parameters.
  388        *
  389        * @return a formatted string describing the parameters, or null if this
  390        * parameter object has not been initialized.
  391        */
  392       public final String toString() {
  393           if (this.initialized == false) {
  394               return null;
  395           }
  396           return paramSpi.engineToString();
  397       }
  398   }

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