home *** CD-ROM | disk | FTP | other *** search
/ Java 1.2 How-To / JavaHowTo.iso / 3rdParty / jbuilder / unsupported / JDK1.2beta3 / SOURCE / SRC.ZIP / java / security / AlgorithmParameters.java < prev    next >
Encoding:
Java Source  |  1998-03-20  |  9.5 KB  |  294 lines
  1. /*
  2.  * @(#)AlgorithmParameters.java    1.9 98/03/18
  3.  *
  4.  * Copyright 1997, 1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.security;
  16.  
  17. import java.io.*;
  18. import java.security.spec.AlgorithmParameterSpec;
  19. import java.security.spec.InvalidParameterSpecException;
  20.  
  21. /**
  22.  * This class is used as an opaque representation of cryptographic parameters.
  23.  * 
  24.  * <p>An <code>AlgorithmParameters</code> object for managing the parameters
  25.  * for a particular algorithm can be obtained by
  26.  * calling one of the <code>getInstance</code> factory methods
  27.  * (static methods that return instances of a given class).
  28.  * 
  29.  * <p>There are two ways to request such an implementation: by
  30.  * specifying either just an algorithm name, or both an algorithm name
  31.  * and a package provider. 
  32.  * 
  33.  * <ul>
  34.  *
  35.  * <li>If just an algorithm name is specified, the system will
  36.  * determine if there is an AlgorithmParameters
  37.  * implementation for the algorithm requested
  38.  * available in the environment, and if there is more than one, if
  39.  * there is a preferred one.
  40.  * 
  41.  * <li>If both an algorithm name and a package provider are specified,
  42.  * the system will determine if there is an implementation 
  43.  * in the package requested, and throw an exception if there
  44.  * is not.
  45.  * 
  46.  * </ul>
  47.  * 
  48.  * <p>Once an <code>AlgorithmParameters</code> object is returned, it must be
  49.  * initialized via a call to <code>init</code>, using an appropriate parameter
  50.  * specification or parameter encoding.
  51.  *
  52.  * <p>A transparent parameter specification is obtained from an
  53.  * <code>AlgorithmParameters</code> object via a call to
  54.  * <code>getParameterSpec</code>, and a byte encoding of the parameters is
  55.  * obtained via a call to <code>getEncoded</code>.
  56.  *
  57.  * @author Jan Luehe
  58.  *
  59.  * @version 1.9, 98/03/18
  60.  *
  61.  * @see java.security.spec.AlgorithmParameterSpec
  62.  * @see java.security.spec.DSAParameterSpec
  63.  * @see KeyPairGenerator
  64.  *
  65.  * @since JDK1.2
  66.  */
  67.  
  68. public class AlgorithmParameters {
  69.  
  70.     // The provider
  71.     private Provider provider;
  72.  
  73.     // The provider implementation (delegate)
  74.     private AlgorithmParametersSpi paramSpi;
  75.  
  76.     // The algorithm
  77.     private String algorithm;
  78.  
  79.     // Has this object been initialized?
  80.     private boolean initialized = false;
  81.  
  82.     /**
  83.      * Creates an AlgorithmParameters object.
  84.      *
  85.      * @param keyFacSpi the delegate
  86.      * @param provider the provider
  87.      * @param algorithm the algorithm
  88.      */
  89.     protected AlgorithmParameters(AlgorithmParametersSpi paramSpi,
  90.                   Provider provider, String algorithm) {
  91.     this.paramSpi = paramSpi;
  92.     this.provider = provider;
  93.     this.algorithm = algorithm;
  94.     }
  95.  
  96.     /**
  97.      * Returns the name of the algorithm associated with the parameter
  98.      * set.
  99.      * 
  100.      * @return the algorithm name.
  101.      */
  102.     public final String getAlgorithm() {
  103.         return algorithm;
  104.     }
  105.  
  106.     /**
  107.      * Generates an AlgorithmParameters object that implements the specified digest
  108.      * algorithm. If the default provider package
  109.      * provides an implementation of the requested digest algorithm,
  110.      * an instance of AlgorithmParameters containing that implementation is returned.
  111.      * If the algorithm is not available in the default 
  112.      * package, other packages are searched.
  113.      *
  114.      * @param algorithm the name of the algorithm requested. 
  115.      *
  116.      * @return the new AlgorithmParameters object.
  117.      *
  118.      * @exception NoSuchAlgorithmException if the algorithm is
  119.      * not available in the environment.
  120.      */
  121.     public static final AlgorithmParameters getInstance(String algorithm) 
  122.     throws NoSuchAlgorithmException {
  123.     try {
  124.         Object[] objs = Security.getImpl(algorithm, "AlgorithmParameters",
  125.                          null);
  126.         return new AlgorithmParameters((AlgorithmParametersSpi)objs[0],
  127.                        (Provider)objs[1],
  128.                        algorithm);
  129.     } catch(NoSuchProviderException e) {
  130.         throw new NoSuchAlgorithmException(algorithm + " not found");
  131.     }
  132.     }
  133.  
  134.     /** 
  135.      * Generates an AlgorithmParameters object for the specified
  136.      * algorithm, as supplied from the specified provider, if such an 
  137.      * algorithm is available from the provider.
  138.      *
  139.      * @param algorithm the name of the algorithm requested.
  140.      *
  141.      * @param provider the name of the provider.
  142.      *
  143.      * @return the new AlgorithmParameters object.
  144.      *
  145.      * @exception NoSuchAlgorithmException if the algorithm is
  146.      * not available in the package supplied by the requested
  147.      * provider.
  148.      *
  149.      * @exception NoSuchProviderException if the provider is not
  150.      * available in the environment. 
  151.      * 
  152.      * @see Provider 
  153.      */
  154.     public static final AlgorithmParameters getInstance(String algorithm,
  155.                           String provider)
  156.     throws NoSuchAlgorithmException, NoSuchProviderException {
  157.  
  158.     Object[] objs = Security.getImpl(algorithm, "AlgorithmParameters",
  159.                      provider);
  160.     return new AlgorithmParameters((AlgorithmParametersSpi)objs[0],
  161.                        (Provider)objs[1],
  162.                        algorithm);
  163.     }
  164.  
  165.     /** 
  166.      * Returns the provider of this algorithm parameter object.
  167.      * 
  168.      * @return the provider of this algorithm parameter object
  169.      */
  170.     public final Provider getProvider() {
  171.     return this.provider;
  172.     }
  173.  
  174.     /**
  175.      * Initializes this parameters object using the parameters 
  176.      * specified in <code>paramSpec</code>.
  177.      *
  178.      * @param paramSpec the parameter specification.
  179.      *
  180.      * @exception InvalidParameterSpecException if the given parameter
  181.      * specification is inappropriate for the initialization of this parameter
  182.      * object.
  183.      */
  184.     public final void init(AlgorithmParameterSpec paramSpec) 
  185.     throws InvalidParameterSpecException {
  186.         paramSpi.engineInit(paramSpec);
  187.         this.initialized = true;
  188.     }
  189.  
  190.     /**
  191.      * Imports the specified parameters and decodes them according to the 
  192.      * primary decoding format for parameters. The primary decoding
  193.      * format for parameters is ASN.1, if an ASN.1 specification for this type
  194.      * of parameters exists.
  195.      *
  196.      * @param params the encoded parameters.
  197.      *
  198.      * @exception IOException on decoding errors
  199.      */
  200.     public final void init(byte[] params) throws IOException {
  201.     paramSpi.engineInit(params);
  202.     this.initialized = true;
  203.     }
  204.  
  205.     /**
  206.      * Imports the parameters from <code>params</code> and decodes them 
  207.      * according to the specified decoding format.
  208.      * If <code>format</code> is null, the
  209.      * primary decoding format for parameters is used. The primary decoding
  210.      * format is ASN.1, if an ASN.1 specification for these parameters
  211.      * exists.
  212.      *
  213.      * @param params the encoded parameters.
  214.      *
  215.      * @param format the name of the decoding format
  216.      *
  217.      * @exception IOException on decoding errors
  218.      */
  219.     public final void init(byte[] params, String format) throws IOException {
  220.     paramSpi.engineInit(params, format);
  221.     this.initialized = true;
  222.     }
  223.  
  224.     /**
  225.      * Returns a (transparent) specification of this parameters object.
  226.      * <code>paramSpec</code> identifies the specification class in which 
  227.      * the parameters should be returned. It could, for example, be
  228.      * <code>DSAParameterSpec.class</code>, to indicate that the
  229.      * parameters should be returned in an instance of the 
  230.      * <code>DSAParameterSpec</code> class.
  231.      *
  232.      * @param paramSpec the specification class in which 
  233.      * the parameters should be returned.
  234.      *
  235.      * @return the parameter specification.
  236.      *
  237.      * @exception InvalidParameterSpecException if the requested parameter
  238.      * specification is inappropriate for this parameter object.
  239.      */
  240.     public final AlgorithmParameterSpec getParameterSpec(Class paramSpec)
  241.     throws InvalidParameterSpecException {
  242.         return paramSpi.engineGetParameterSpec(paramSpec);
  243.     }
  244.  
  245.     /**
  246.      * Returns the parameters in their primary encoding format.
  247.      * The primary encoding format for parameters is ASN.1, if an ASN.1
  248.      * specification for this type of parameters exists.
  249.      *
  250.      * @return the parameters encoded using the specified encoding scheme.
  251.      *
  252.      * @exception IOException on encoding errors.
  253.      */
  254.     public final byte[] getEncoded() throws IOException {
  255.     if (this.initialized == false) {
  256.         throw new IOException("Uninitialized parameters");
  257.     }
  258.     return paramSpi.engineGetEncoded();
  259.     }
  260.  
  261.     /**
  262.      * Returns the parameters encoded in the specified format.
  263.      * If <code>format</code> is null, the
  264.      * primary encoding format for parameters is used. The primary encoding
  265.      * format is ASN.1, if an ASN.1 specification for these parameters
  266.      * exists.
  267.      *
  268.      * @param format the name of the encoding format.
  269.      *
  270.      * @return the parameters encoded using the specified encoding scheme.
  271.      *
  272.      * @exception IOException on encoding errors.
  273.      */
  274.     public final byte[] getEncoded(String format) throws IOException {
  275.     if (this.initialized == false) {
  276.         throw new IOException("Uninitialized parameters");
  277.     }
  278.     return paramSpi.engineGetEncoded(format);
  279.     }
  280.  
  281.     /**
  282.      * Returns a formatted string describing the parameters.
  283.      *
  284.      * @return a formatted string describing the parameters, or null if this
  285.      * object has not been initialized.
  286.      */
  287.     public final String toString() {
  288.     if (this.initialized == false) {
  289.         return null;
  290.     }
  291.     return paramSpi.engineToString();
  292.     }
  293. }
  294.