1 /*

     2  * Copyright 1997-2006 Sun Microsystems, Inc.  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.  Sun designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

    22  * CA 95054 USA or visit www.sun.com if you need additional information or

    23  * have any 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  * @author Jan Luehe

    50  *

    51  *

    52  * @see java.security.spec.AlgorithmParameterSpec

    53  * @see java.security.spec.DSAParameterSpec

    54  * @see KeyPairGenerator

    55  *

    56  * @since 1.2

    57  */

    58 

    59 public class AlgorithmParameters {

    60 

    61     // The provider

    62     private Provider provider;

    63 

    64     // The provider implementation (delegate)

    65     private AlgorithmParametersSpi paramSpi;

    66 

    67     // The algorithm

    68     private String algorithm;

    69 

    70     // Has this object been initialized?

    71     private boolean initialized = false;

    72 

    73     /**

    74      * Creates an AlgorithmParameters object.

    75      *

    76      * @param paramSpi the delegate

    77      * @param provider the provider

    78      * @param algorithm the algorithm

    79      */

    80     protected AlgorithmParameters(AlgorithmParametersSpi paramSpi,

    81                                   Provider provider, String algorithm)

    82     {

    83         this.paramSpi = paramSpi;

    84         this.provider = provider;

    85         this.algorithm = algorithm;

    86     }

    87 

    88     /**

    89      * Returns the name of the algorithm associated with this parameter object.

    90      *

    91      * @return the algorithm name.

    92      */

    93     public final String getAlgorithm() {

    94         return this.algorithm;

    95     }

    96 

    97     /**

    98      * Returns a parameter object for the specified algorithm.

    99      *

   100      * <p> This method traverses the list of registered security Providers,

   101      * starting with the most preferred Provider.

   102      * A new AlgorithmParameters object encapsulating the

   103      * AlgorithmParametersSpi implementation from the first

   104      * Provider that supports the specified algorithm is returned.

   105      *

   106      * <p> Note that the list of registered providers may be retrieved via

   107      * the {@link Security#getProviders() Security.getProviders()} method.

   108      *

   109      * <p> The returned parameter object must be initialized via a call to

   110      * <code>init</code>, using an appropriate parameter specification or

   111      * parameter encoding.

   112      *

   113      * @param algorithm the name of the algorithm requested.

   114      * See Appendix A in the <a href=

   115      * "../../../technotes/guides/security/crypto/CryptoSpec.html#AppA">

   116      * Java Cryptography Architecture API Specification &amp; Reference </a>

   117      * for information about standard algorithm names.

   118      *

   119      * @return the new parameter object.

   120      *

   121      * @exception NoSuchAlgorithmException if no Provider supports an

   122      *          AlgorithmParametersSpi implementation for the

   123      *          specified algorithm.

   124      *

   125      * @see Provider

   126      */

   127     public static AlgorithmParameters getInstance(String algorithm)

   128     throws NoSuchAlgorithmException {

   129         try {

   130             Object[] objs = Security.getImpl(algorithm, "AlgorithmParameters",

   131                                              (String)null);

   132             return new AlgorithmParameters((AlgorithmParametersSpi)objs[0],

   133                                            (Provider)objs[1],

   134                                            algorithm);

   135         } catch(NoSuchProviderException e) {

   136             throw new NoSuchAlgorithmException(algorithm + " not found");

   137         }

   138     }

   139 

   140     /**

   141      * Returns a parameter object for the specified algorithm.

   142      *

   143      * <p> A new AlgorithmParameters object encapsulating the

   144      * AlgorithmParametersSpi implementation from the specified provider

   145      * is returned.  The specified provider must be registered

   146      * in the security provider list.

   147      *

   148      * <p> Note that the list of registered providers may be retrieved via

   149      * the {@link Security#getProviders() Security.getProviders()} method.

   150      *

   151      * <p>The returned parameter object must be initialized via a call to

   152      * <code>init</code>, using an appropriate parameter specification or

   153      * parameter encoding.

   154      *

   155      * @param algorithm the name of the algorithm requested.

   156      * See Appendix A in the <a href=

   157      * "../../../technotes/guides/security/crypto/CryptoSpec.html#AppA">

   158      * Java Cryptography Architecture API Specification &amp; Reference </a>

   159      * for information about standard algorithm names.

   160      *

   161      * @param provider the name of the provider.

   162      *

   163      * @return the new parameter object.

   164      *

   165      * @exception NoSuchAlgorithmException if an AlgorithmParametersSpi

   166      *          implementation for the specified algorithm is not

   167      *          available from the specified provider.

   168      *

   169      * @exception NoSuchProviderException if the specified provider is not

   170      *          registered in the security provider list.

   171      *

   172      * @exception IllegalArgumentException if the provider name is null

   173      *          or empty.

   174      *

   175      * @see Provider

   176      */

   177     public static AlgorithmParameters getInstance(String algorithm,

   178                                                   String provider)

   179         throws NoSuchAlgorithmException, NoSuchProviderException

   180     {

   181         if (provider == null || provider.length() == 0)

   182             throw new IllegalArgumentException("missing provider");

   183         Object[] objs = Security.getImpl(algorithm, "AlgorithmParameters",

   184                                          provider);

   185         return new AlgorithmParameters((AlgorithmParametersSpi)objs[0],

   186                                        (Provider)objs[1],

   187                                        algorithm);

   188     }

   189 

   190     /**

   191      * Returns a parameter object for the specified algorithm.

   192      *

   193      * <p> A new AlgorithmParameters object encapsulating the

   194      * AlgorithmParametersSpi implementation from the specified Provider

   195      * object is returned.  Note that the specified Provider object

   196      * does not have to be registered in the provider list.

   197      *

   198      * <p>The returned parameter object must be initialized via a call to

   199      * <code>init</code>, using an appropriate parameter specification or

   200      * parameter encoding.

   201      *

   202      * @param algorithm the name of the algorithm requested.

   203      * See Appendix A in the <a href=

   204      * "../../../technotes/guides/security/crypto/CryptoSpec.html#AppA">

   205      * Java Cryptography Architecture API Specification &amp; Reference </a>

   206      * for information about standard algorithm names.

   207      *

   208      * @param provider the name of the provider.

   209      *

   210      * @return the new parameter object.

   211      *

   212      * @exception NoSuchAlgorithmException if an AlgorithmParameterGeneratorSpi

   213      *          implementation for the specified algorithm is not available

   214      *          from the specified Provider object.

   215      *

   216      * @exception IllegalArgumentException if the provider is null.

   217      *

   218      * @see Provider

   219      *

   220      * @since 1.4

   221      */

   222     public static AlgorithmParameters getInstance(String algorithm,

   223                                                   Provider provider)

   224         throws NoSuchAlgorithmException

   225     {

   226         if (provider == null)

   227             throw new IllegalArgumentException("missing provider");

   228         Object[] objs = Security.getImpl(algorithm, "AlgorithmParameters",

   229                                          provider);

   230         return new AlgorithmParameters((AlgorithmParametersSpi)objs[0],

   231                                        (Provider)objs[1],

   232                                        algorithm);

   233     }

   234 

   235     /**

   236      * Returns the provider of this parameter object.

   237      *

   238      * @return the provider of this parameter object

   239      */

   240     public final Provider getProvider() {

   241         return this.provider;

   242     }

   243 

   244     /**

   245      * Initializes this parameter object using the parameters

   246      * specified in <code>paramSpec</code>.

   247      *

   248      * @param paramSpec the parameter specification.

   249      *

   250      * @exception InvalidParameterSpecException if the given parameter

   251      * specification is inappropriate for the initialization of this parameter

   252      * object, or if this parameter object has already been initialized.

   253      */

   254     public final void init(AlgorithmParameterSpec paramSpec)

   255         throws InvalidParameterSpecException

   256     {

   257         if (this.initialized)

   258             throw new InvalidParameterSpecException("already initialized");

   259         paramSpi.engineInit(paramSpec);

   260         this.initialized = true;

   261     }

   262 

   263     /**

   264      * Imports the specified parameters and decodes them according to the

   265      * primary decoding format for parameters. The primary decoding

   266      * format for parameters is ASN.1, if an ASN.1 specification for this type

   267      * of parameters exists.

   268      *

   269      * @param params the encoded parameters.

   270      *

   271      * @exception IOException on decoding errors, or if this parameter object

   272      * has already been initialized.

   273      */

   274     public final void init(byte[] params) throws IOException {

   275         if (this.initialized)

   276             throw new IOException("already initialized");

   277         paramSpi.engineInit(params);

   278         this.initialized = true;

   279     }

   280 

   281     /**

   282      * Imports the parameters from <code>params</code> and decodes them

   283      * according to the specified decoding scheme.

   284      * If <code>format</code> is null, the

   285      * primary decoding format for parameters is used. The primary decoding

   286      * format is ASN.1, if an ASN.1 specification for these parameters

   287      * exists.

   288      *

   289      * @param params the encoded parameters.

   290      *

   291      * @param format the name of the decoding scheme.

   292      *

   293      * @exception IOException on decoding errors, or if this parameter object

   294      * has already been initialized.

   295      */

   296     public final void init(byte[] params, String format) throws IOException {

   297         if (this.initialized)

   298             throw new IOException("already initialized");

   299         paramSpi.engineInit(params, format);

   300         this.initialized = true;

   301     }

   302 

   303     /**

   304      * Returns a (transparent) specification of this parameter object.

   305      * <code>paramSpec</code> identifies the specification class in which

   306      * the parameters should be returned. It could, for example, be

   307      * <code>DSAParameterSpec.class</code>, to indicate that the

   308      * parameters should be returned in an instance of the

   309      * <code>DSAParameterSpec</code> class.

   310      *

   311      * @param paramSpec the specification class in which

   312      * the parameters should be returned.

   313      *

   314      * @return the parameter specification.

   315      *

   316      * @exception InvalidParameterSpecException if the requested parameter

   317      * specification is inappropriate for this parameter object, or if this

   318      * parameter object has not been initialized.

   319      */

   320     public final <T extends AlgorithmParameterSpec>

   321         T getParameterSpec(Class<T> paramSpec)

   322         throws InvalidParameterSpecException

   323     {

   324         if (this.initialized == false) {

   325             throw new InvalidParameterSpecException("not initialized");

   326         }

   327         return paramSpi.engineGetParameterSpec(paramSpec);

   328     }

   329 

   330     /**

   331      * Returns the parameters in their primary encoding format.

   332      * The primary encoding format for parameters is ASN.1, if an ASN.1

   333      * specification for this type of parameters exists.

   334      *

   335      * @return the parameters encoded using their primary encoding format.

   336      *

   337      * @exception IOException on encoding errors, or if this parameter object

   338      * has not been initialized.

   339      */

   340     public final byte[] getEncoded() throws IOException

   341     {

   342         if (this.initialized == false) {

   343             throw new IOException("not initialized");

   344         }

   345         return paramSpi.engineGetEncoded();

   346     }

   347 

   348     /**

   349      * Returns the parameters encoded in the specified scheme.

   350      * If <code>format</code> is null, the

   351      * primary encoding format for parameters is used. The primary encoding

   352      * format is ASN.1, if an ASN.1 specification for these parameters

   353      * exists.

   354      *

   355      * @param format the name of the encoding format.

   356      *

   357      * @return the parameters encoded using the specified encoding scheme.

   358      *

   359      * @exception IOException on encoding errors, or if this parameter object

   360      * has not been initialized.

   361      */

   362     public final byte[] getEncoded(String format) throws IOException

   363     {

   364         if (this.initialized == false) {

   365             throw new IOException("not initialized");

   366         }

   367         return paramSpi.engineGetEncoded(format);

   368     }

   369 

   370     /**

   371      * Returns a formatted string describing the parameters.

   372      *

   373      * @return a formatted string describing the parameters, or null if this

   374      * parameter object has not been initialized.

   375      */

   376     public final String toString() {

   377         if (this.initialized == false) {

   378             return null;

   379         }

   380         return paramSpi.engineToString();

   381     }

   382 }