Makefile.in: Rebuilt.

	* Makefile.in: Rebuilt.
	* Makefile.am (ordinary_java_source_files): Added new files.
	* java/security/AlgorithmParameterGenerator.java,
	java/security/AlgorithmParameters.java, java/security/Engine.java,
	java/security/Identity.java, java/security/IdentityScope.java,
	java/security/KeyFactory.java,
	java/security/KeyPairGenerator.java, java/security/KeyStore.java,
	java/security/MessageDigest.java, java/security/Policy.java,
	java/security/ProtectionDomain.java,
	java/security/SecureRandom.java, java/security/Security.java,
	java/security/Signature.java, java/security/SignatureSpi.java,
	java/security/SignedObject.java, java/security/Signer.java,
	java/security/interfaces/RSAMultiPrimePrivateCrtKey.java,
	java/security/spec/PSSParameterSpec.java,
	java/security/spec/RSAMultiPrimePrivateCrtKeySpec.java,
	java/security/spec/RSAOtherPrimeInfo.java: New versions from
	Classpath.

From-SVN: r65829

1 files changed, 368 insertions, 260 deletions

diff --git a/libjava/java/security/Signature.java b/libjava/java/security/Signature.java
index 209a7df..dff2e2d 100644
--- a/libjava/java/security/Signature.java
+++ b/libjava/java/security/Signature.java
@@ -1,5 +1,5 @@
 /* Signature.java --- Signature Class
-   Copyright (C) 1999, 2002 Free Software Foundation, Inc.
+   Copyright (C) 1999, 2002, 2003 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -36,73 +36,113 @@ obligated to do so.  If you do not wish to do so, delete this
 exception statement from your version. */
 
 package java.security;
+
+import java.security.cert.Certificate;
+import java.security.cert.X509Certificate;
 import java.security.spec.AlgorithmParameterSpec;
 
 /**
-   Signature is used to provide an interface to digital signature 
-   algorithms. Digital signatures provide authentication and data 
-   integrity of digital data. 
-
-   The GNU provider provides the NIST standard DSA which uses DSA 
-   and SHA-1. It can be specified by SHA/DSA, SHA-1/DSA or its 
-   OID. If the RSA signature algorithm is provided then
-   it could be MD2/RSA. MD5/RSA, or SHA-1/RSA. The algorithm must
-   be specified because there is no default.
-
-   Signature provides implementation-independent algorithms which 
-   are requested by the user through getInstance. It can be 
-   requested by specifying just the algorithm name or by 
-   specifying both the algorithm name and provider name. 
-
-   The three phases of using Signature are:
-
-   1. Initialing
-
-   * It must be initialized with a private key for signing.
-   * It must be initialized with a public key for verifying.
-
-   2. Updating
-
-   Update the bytes for signing or verifying with calls to update.
-
-   3. Signing or Verify the signature on the currently stored
-   bytes by calling sign or verify.
-
-   @author Mark Benvenuto <ivymccough@worldnet.att.net>
-   @since JDK 1.1
+ * <p>This <code>Signature</code> class is used to provide applications the
+ * functionality of a digital signature algorithm. Digital signatures are used
+ * for authentication and integrity assurance of digital data.</p>
+ *
+ * <p>The signature algorithm can be, among others, the NIST standard <i>DSS</i>,
+ * using <i>DSA</i> and <i>SHA-1</i>. The <i>DSA</i> algorithm using the
+ * <i>SHA-1</i> message digest algorithm can be specified as <code>SHA1withDSA
+ * </code>. In the case of <i>RSA</i>, there are multiple choices for the
+ * message digest algorithm, so the signing algorithm could be specified as, for
+ * example, <code>MD2withRSA</code>, <code>MD5withRSA</code>, or
+ * <code>SHA1withRSA</code>. The algorithm name must be specified, as there is
+ * no default.</p>
+ *
+ * <p>Like other algorithm-based classes in Java Security, <code>Signature</code>
+ * provides implementation-independent algorithms, whereby a caller (application
+ * code) requests a particular signature algorithm and is handed back a properly
+ * initialized <code>Signature</code> object. It is also possible, if desired,
+ * to request a particular algorithm from a particular provider. See the
+ * <code>getInstance()</code> methods.</p>
+ *
+ * <p>Thus, there are two ways to request a <code>Signature</code> algorithm
+ * object: by specifying either just an algorithm name, or both an algorithm
+ * name and a package provider.</p>
+ *
+ * <p>If just an algorithm name is specified, the system will determine if there
+ * is an implementation of the algorithm requested available in the environment,
+ * and if there is more than one, if there is a preferred one.</p>
+ *
+ * <p>If both an algorithm name and a package provider are specified, the system
+ * will determine if there is an implementation of the algorithm in the package
+ * requested, and throw an exception if there is not.</p>
+ *
+ * <p>A <code>Signature</code> object can be used to generate and verify digital
+ * signatures.</p>
+ *
+ * <p>There are three phases to the use of a <code>Signature</code> object for
+ * either signing data or verifying a signature:</p>
+ *
+ * <ol>
+ *    <li>Initialization, with either
+ *      <ul>
+ *        <li>a public key, which initializes the signature for verification
+ *        (see <code>initVerify()</code>), or</li>
+ *        <li>a private key (and optionally a Secure Random Number Generator),
+ *        which initializes the signature for signing (see
+ *        {@link #initSign(PrivateKey)} and {@link #initSign(PrivateKey, SecureRandom)}
+ *        ).</li>
+ *      </ul></li>
+ *    <li>Updating<br/>
+ *      Depending on the type of initialization, this will update the bytes to
+ *      be signed or verified. See the update methods.<br/></li>
+ *    <li>Signing or Verifying a signature on all updated bytes. See the
+ *    <code>sign()</code> methods and the <code>verify()</code> method.</li>
+ *  </ol>
+ *
+ * <p>Note that this class is abstract and extends from {@link SignatureSpi} for
+ * historical reasons. Application developers should only take notice of the
+ * methods defined in this <code>Signature</code> class; all the methods in the
+ * superclass are intended for cryptographic service providers who wish to
+ * supply their own implementations of digital signature algorithms.
+ *
+ * @author Mark Benvenuto <ivymccough@worldnet.att.net>
  */
 public abstract class Signature extends SignatureSpi
 {
+  /** Service name for signatures. */
+  private static final String SIGNATURE = "Signature";
+
   /**
-     Possible state variable which signifies if it has not been 
-     initialized.
+   * Possible <code>state</code> value, signifying that this signature object
+   * has not yet been initialized.
    */
-  protected static final int UNINITIALIZED = 1;
+  protected static final int UNINITIALIZED = 0;
+
+  // Constructor.
+  // ------------------------------------------------------------------------
 
   /**
-     Possible state variable which signifies if it has been 
-     initialized for signing.
+   * Possible <code>state</code> value, signifying that this signature object
+   * has been initialized for signing.
    */
   protected static final int SIGN = 2;
 
   /**
-     Possible state variable which signifies if it has been 
-     initialized for verifying.
+   * Possible <code>state</code> value, signifying that this signature object
+   * has been initialized for verification.
    */
   protected static final int VERIFY = 3;
 
-  /**
-     State of this Signature class.
-   */
+  /** Current state of this signature object. */
   protected int state = UNINITIALIZED;
 
   private String algorithm;
   Provider provider;
 
   /**
-     Creates a new signature for this algorithm.
-
-     @param algorithm the algorithm to use
+   * Creates a <code>Signature</code> object for the specified algorithm.
+   *
+   * @param algorithm the standard string name of the algorithm. See Appendix A
+   * in the Java Cryptography Architecture API Specification &amp; Reference for
+   * information about standard algorithm names.
    */
   protected Signature(String algorithm)
   {
@@ -111,21 +151,24 @@ public abstract class Signature extends SignatureSpi
   }
 
   /**
-     Gets an instance of the Signature class representing
-     the specified signature. If the algorithm is not found then, 
-     it throws NoSuchAlgorithmException.
-
-     @param algorithm the name of signature algorithm to choose
-     @return a Signature repesenting the desired algorithm
-
-     @throws NoSuchAlgorithmException if the algorithm is not implemented by
-     				      providers
+   * Generates a <code>Signature</code> object that implements the specified
+   * digest algorithm. If the default provider package provides an
+   * implementation of the requested digest algorithm, an instance of
+   * <code>Signature</code> containing that implementation is returned. If the
+   * algorithm is not available in the default package, other packages are
+   * searched.
+   *
+   * @param algorithm the standard name of the algorithm requested. See Appendix
+   * A in the Java Cryptography Architecture API Specification &amp; Reference
+   * for information about standard algorithm names.
+   * @return the new Signature object.
+   * @throws NoSuchAlgorithmException if the algorithm is not available in the
+   * environment.
    */
   public static Signature getInstance(String algorithm)
     throws NoSuchAlgorithmException
   {
     Provider[] p = Security.getProviders();
-
     for (int i = 0; i < p.length; i++)
       {
         try
@@ -138,24 +181,30 @@ public abstract class Signature extends SignatureSpi
     throw new NoSuchAlgorithmException(algorithm);
   }
 
-  /** 
-     Gets an instance of the Signature class representing
-     the specified signature from the specified provider. If the 
-     algorithm is not found then, it throws NoSuchAlgorithmException.
-     If the provider is not found, then it throws
-     NoSuchProviderException.
-
-     @param algorithm the name of signature algorithm to choose
-     @param provider the name of the provider to find the algorithm in
-     @return a Signature repesenting the desired algorithm
-
-     @throws NoSuchAlgorithmException if the algorithm is not implemented by
-				      the provider
-     @throws NoSuchProviderException if the provider is not found
+  /**
+   * Generates a <code>Signature</code> object implementing the specified
+   * algorithm, as supplied from the specified provider, if such an algorithm
+   * is available from the provider.
+   *
+   * @param algorithm the name of the algorithm requested. See Appendix A in
+   * the Java Cryptography Architecture API Specification &amp; Reference for
+   * information about standard algorithm names.
+   * @param provider the name of the provider.
+   * @return the new <code>Signature</code> object.
+   * @throws NoSuchAlgorithmException if the algorithm is not available in the
+   * package supplied by the requested provider.
+   * @throws NoSuchProviderException if the provider is not available in the
+   * environment.
+   * @throws IllegalArgumentException if the provider name is <code>null</code>
+   * or empty.
+   * @see Provider
    */
   public static Signature getInstance(String algorithm, String provider)
     throws NoSuchAlgorithmException, NoSuchProviderException
   {
+    if (provider == null || provider.length() == 0)
+      throw new IllegalArgumentException("Illegal provider");
+    
     Provider p = Security.getProvider(provider);
     if (p == null)
       throw new NoSuchProviderException(provider);
@@ -163,69 +212,54 @@ public abstract class Signature extends SignatureSpi
     return getInstance(algorithm, p);
   }
 
-  private static Signature getInstance(String algorithm, Provider p)
+  /**
+   * Generates a <code>Signature</code> object implementing the specified
+   * algorithm, as supplied from the specified provider, if such an algorithm
+   * is available from the provider. Note: the provider doesn't have to be
+   * registered.
+   *
+   * @param algorithm the name of the algorithm requested. See Appendix A in
+   * the Java Cryptography Architecture API Specification &amp; Reference for
+   * information about standard algorithm names.
+   * @param provider the provider.
+   * @return the new <code>Signature</code> object.
+   * @throws NoSuchAlgorithmException if the <code>algorithm</code> is not
+   * available in the package supplied by the requested <code>provider</code>.
+   * @throws IllegalArgumentException if the <code>provider</code> is
+   * <code>null</code>.
+   * @since 1.4
+   * @see Provider
+   */
+  public static Signature getInstance(String algorithm, Provider provider)
     throws NoSuchAlgorithmException
   {
-    // try the name as is
-    String className = p.getProperty("Signature." + algorithm);
-    if (className == null) { // try all uppercase
-      String upper = algorithm.toUpperCase();
-      className = p.getProperty("Signature." + upper);
-      if (className == null) { // try if it's an alias
-        String alias = p.getProperty("Alg.Alias.Signature." + algorithm);
-        if (alias == null) {
-          alias = p.getProperty("Alg.Alias.Signature." + upper);
-          if (alias == null) { // spit the dummy
-            throw new NoSuchAlgorithmException(algorithm);
-          }
-        }
-        className = p.getProperty("Signature." + alias);
-        if (className == null) {
-          throw new NoSuchAlgorithmException(algorithm);
-        }
-      }
-    }
-    return getInstance(className, algorithm, p);
-  }
+    if (provider == null)
+      throw new IllegalArgumentException("Illegal provider");
 
-  private static Signature getInstance(String classname,
-				       String algorithm,
-				       Provider provider)
-    throws NoSuchAlgorithmException
-  {
-    try
-      {
-	Object o = Class.forName(classname).newInstance();
-	Signature sig;
-	if (o instanceof SignatureSpi)
-	  sig = new DummySignature((SignatureSpi) o, algorithm);
-	else
-	  {
-	    sig = (Signature) o;
-	    sig.algorithm = algorithm;
-	  }
-
-	sig.provider = provider;
-	return sig;
-      }
-    catch (ClassNotFoundException cnfe)
+    Signature result = null;
+    Object o = Engine.getInstance(SIGNATURE, algorithm, provider);
+
+    if (o instanceof SignatureSpi)
       {
-	throw new NoSuchAlgorithmException("Class not found");
+	result = new DummySignature((SignatureSpi) o, algorithm);
       }
-    catch (InstantiationException ie)
+    else if (o instanceof Signature)
       {
-	throw new NoSuchAlgorithmException("Class instantiation failed");
+	result = (Signature) o;
+	result.algorithm = algorithm;
       }
-    catch (IllegalAccessException iae)
+    else
       {
-	throw new NoSuchAlgorithmException("Illegal Access");
+	throw new NoSuchAlgorithmException(algorithm);
       }
+    result.provider = provider;
+    return result;
   }
 
   /**
-     Gets the provider that the Signature is from.
-
-     @return the provider of this Signature
+   * Returns the provider of this signature object.
+   *
+   * @return the provider of this signature object.
    */
   public final Provider getProvider()
   {
@@ -233,12 +267,12 @@ public abstract class Signature extends SignatureSpi
   }
 
   /**
-     Initializes this class with the public key for 
-     verification purposes.
-
-     @param publicKey the public key to verify with
-
-     @throws InvalidKeyException invalid key
+   * Initializes this object for verification. If this method is called again
+   * with a different argument, it negates the effect of this call.
+   *
+   * @param publicKey the public key of the identity whose signature is going
+   * to be verified.
+   * @throws InvalidKeyException if the key is invalid.
    */
   public final void initVerify(PublicKey publicKey) throws InvalidKeyException
   {
@@ -247,39 +281,43 @@ public abstract class Signature extends SignatureSpi
   }
 
   /**
-     Verify Signature with a certificate. This is a FIPS 140-1 compatible method
-     since it verifies a signature with a certificate.
-
-     If the certificate is an X.509 certificate, has a KeyUsage parameter and
-     the parameter indicates this key is not to be used for signing then an 
-     error is returned.
-
-     @param certificate a certificate containing a public key to verify with
+   * <p>Initializes this object for verification, using the public key from the
+   * given certificate.</p>
+   *
+   * <p>If the certificate is of type <i>X.509</i> and has a <i>key usage</i>
+   * extension field marked as <i>critical</i>, and the value of the <i>key
+   * usage</i> extension field implies that the public key in the certificate
+   * and its corresponding private key are not supposed to be used for digital
+   * signatures, an {@link InvalidKeyException} is thrown.</p>
+   *
+   * @param certificate the certificate of the identity whose signature is
+   * going to be verified.
+   * @throws InvalidKeyException if the public key in the certificate is not
+   * encoded properly or does not include required parameter information or
+   * cannot be used for digital signature purposes.
    */
-  public final void initVerify(java.security.cert.Certificate certificate)
+  public final void initVerify(Certificate certificate)
     throws InvalidKeyException
   {
     state = VERIFY;
     if (certificate.getType().equals("X509"))
       {
-	java.security.cert.X509Certificate cert =
-	  (java.security.cert.X509Certificate) certificate;
-
+        X509Certificate cert = (X509Certificate) certificate;
 	boolean[]array = cert.getKeyUsage();
 	if (array != null && array[0] == false)
-	  throw new InvalidKeyException
-	    ("KeyUsage of this Certificate indicates it cannot be used for digital signing");
+	  throw new InvalidKeyException(
+              "KeyUsage of this Certificate indicates it cannot be used for digital signing");
       }
     this.initVerify(certificate.getPublicKey());
   }
 
   /**
-     Initializes this class with the private key for 
-     signing purposes.
-
-     @param privateKey the private key to sign with
-
-     @throws InvalidKeyException invalid key
+   * Initialize this object for signing. If this method is called again with a
+   * different argument, it negates the effect of this call.
+   *
+   * @param privateKey the private key of the identity whose signature is going
+   * to be generated.
+   * @throws InvalidKeyException if the key is invalid.
    */
   public final void initSign(PrivateKey privateKey) throws InvalidKeyException
   {
@@ -288,15 +326,13 @@ public abstract class Signature extends SignatureSpi
   }
 
   /**
-     Initializes this class with the private key and source 
-     of randomness for signing purposes.
-
-     @param privateKey the private key to sign with
-     @param random Source of randomness
-
-     @throws InvalidKeyException invalid key
-
-     @since JDK 1.2
+   * Initialize this object for signing. If this method is called again with a
+   * different argument, it negates the effect of this call.
+   *
+   * @param privateKey the private key of the identity whose signature is going
+   * to be generated.
+   * @param random the source of randomness for this signature.
+   * @throws InvalidKeyException if the key is invalid.
    */
   public final void initSign(PrivateKey privateKey, SecureRandom random)
     throws InvalidKeyException
@@ -305,91 +341,137 @@ public abstract class Signature extends SignatureSpi
     engineInitSign(privateKey, random);
   }
 
-
   /**
-     Returns the signature bytes of all the data fed to this class.
-     The format of the output depends on the underlying signature
-     algorithm.
-
-     @return the signature
-
-     @throws SignatureException engine not properly initialized
+   * <p>Returns the signature bytes of all the data updated. The format of the
+   * signature depends on the underlying signature scheme.</p>
+   *
+   * <p>A call to this method resets this signature object to the state it was
+   * in when previously initialized for signing via a call to
+   * <code>initSign(PrivateKey)</code>. That is, the object is reset and
+   * available to generate another signature from the same signer, if desired,
+   * via new calls to <code>update()</code> and <code>sign()</code>.</p>
+   *
+   * @return the signature bytes of the signing operation's result.
+   * @throws SignatureException if this signature object is not initialized
+   * properly.
    */
   public final byte[] sign() throws SignatureException
   {
     if (state == SIGN)
       {
-	state = UNINITIALIZED;
-	return engineSign();
+        state = UNINITIALIZED;
+        return engineSign();
       }
     else
       throw new SignatureException();
   }
 
   /**
-     Generates signature bytes of all the data fed to this class 
-     and outputs it to the passed array. The format of the 
-     output depends on the underlying signature algorithm.
-
-     After calling this method, the signature is reset to its
-     initial state and can be used to generate additional
-     signatures.
-
-     @param outbuf array of bytes
-     @param offset the offset to start at in the array
-     @param len the length of the bytes to put into the array. 
-     Neither this method or the GNU provider will 
-     return partial digests. If len is less than the 
-     signature length, this method will throw 
-     SignatureException. If it is greater than or equal
-     then it is ignored.
-
-     @return number of bytes in outbuf
-
-     @throws SignatureException engine not properly initialized
-
-     @since JDK 1.2
+   * <p>Finishes the signature operation and stores the resulting signature
+   * bytes in the provided buffer <code>outbuf</code>, starting at <code>offset
+   * </code>. The format of the signature depends on the underlying signature
+   * scheme.</p>
+   *
+   * <p>This signature object is reset to its initial state (the state it was
+   * in after a call to one of the <code>initSign()</code> methods) and can be
+   * reused to generate further signatures with the same private key.</p>
+   *
+   * @param outbuf buffer for the signature result.
+   * @param offset offset into outbuf where the signature is stored.
+   * @param len number of bytes within outbuf allotted for the signature.
+   * @return the number of bytes placed into outbuf.
+   * @throws SignatureException if an error occurs or len is less than the
+   * actual signature length.
+   * @since 1.2
    */
   public final int sign(byte[] outbuf, int offset, int len)
     throws SignatureException
   {
     if (state == SIGN)
       {
-	state = UNINITIALIZED;
-	return engineSign(outbuf, offset, len);
+        state = UNINITIALIZED;
+        return engineSign(outbuf, offset, len);
       }
     else
       throw new SignatureException();
   }
 
   /**
-     Verifies the passed signature.
-
-     @param signature the signature bytes to verify
-
-     @return true if verified, false otherwise
-
-     @throws SignatureException engine not properly initialized
-     or wrong signature
+   * <p>Verifies the passed-in signature.</p>
+   *
+   * <p>A call to this method resets this signature object to the state it was
+   * in when previously initialized for verification via a call to
+   * <code>initVerify(PublicKey)</code>. That is, the object is reset and
+   * available to verify another signature from the identity whose public key
+   * was specified in the call to <code>initVerify()</code>.</p>
+   *
+   * @param signature the signature bytes to be verified.
+   * @return <code>true</code> if the signature was verified, <code>false</code>
+   * if not.
+   * @throws SignatureException if this signature object is not initialized
+   * properly, or the passed-in signature is improperly encoded or of the wrong
+   * type, etc.
    */
   public final boolean verify(byte[]signature) throws SignatureException
   {
     if (state == VERIFY)
       {
-	state = UNINITIALIZED;
-	return engineVerify(signature);
+        state = UNINITIALIZED;
+        return engineVerify(signature);
       }
     else
       throw new SignatureException();
   }
 
   /**
-     Updates the data to be signed or verified with the specified 
-     byte.
+   * <p>Verifies the passed-in <code>signature</code> in the specified array of
+   * bytes, starting at the specified <code>offset</code>.</p>
+   *
+   * <p>A call to this method resets this signature object to the state it was
+   * in when previously initialized for verification via a call to
+   * <code>initVerify(PublicKey)</code>. That is, the object is reset and
+   * available to verify another signature from the identity whose public key
+   * was specified in the call to <code>initVerify()</code>.</p>
+   *
+   * @param signature the signature bytes to be verified.
+   * @param offset the offset to start from in the array of bytes.
+   * @param length the number of bytes to use, starting at offset.
+   * @return <code>true</code> if the signature was verified, <code>false</code>
+   * if not.
+   * @throws SignatureException if this signature object is not initialized
+   * properly, or the passed-in <code>signature</code> is improperly encoded or
+   * of the wrong type, etc.
+   * @throws IllegalArgumentException if the <code>signature</code> byte array
+   * is <code>null</code>, or the <code>offset</code> or <code>length</code> is
+   * less than <code>0</code>, or the sum of the <code>offset</code> and
+   * <code>length</code> is greater than the length of the <code>signature</code>
+   * byte array.
+   */
+  public final boolean verify(byte[] signature, int offset, int length)
+    throws SignatureException
+  {
+    if (state != VERIFY)
+      throw new SignatureException("illegal state");
+
+    if (signature == null)
+      throw new IllegalArgumentException("signaure is null");
+    if (offset < 0)
+      throw new IllegalArgumentException("offset is less than 0");
+    if (length < 0)
+      throw new IllegalArgumentException("length is less than 0");
+    if (offset + length < signature.length)
+      throw new IllegalArgumentException("range is out of bounds");
 
-     @param b byte to update with
+    state = UNINITIALIZED;
+    return engineVerify(signature, offset, length);
+  }
 
-     @throws SignatureException Engine not properly initialized
+  /**
+   * Updates the data to be signed or verified by a byte.
+   *
+   * @param b the byte to use for the update.
+   * @throws SignatureException if this signature object is not initialized
+   * properly.
    */
   public final void update(byte b) throws SignatureException
   {
@@ -400,12 +482,12 @@ public abstract class Signature extends SignatureSpi
   }
 
   /**
-     Updates the data to be signed or verified with the specified 
-     bytes.
-
-     @param data array of bytes
-
-     @throws SignatureException engine not properly initialized
+   * Updates the data to be signed or verified, using the specified array of
+   * bytes.
+   *
+   * @param data the byte array to use for the update.
+   * @throws SignatureException if this signature object is not initialized
+   * properly.
    */
   public final void update(byte[]data) throws SignatureException
   {
@@ -416,14 +498,14 @@ public abstract class Signature extends SignatureSpi
   }
 
   /**
-     Updates the data to be signed or verified with the specified 
-     bytes.
-
-     @param data array of bytes
-     @param off the offset to start at in the array
-     @param len the length of the bytes to use in the array
-
-     @throws SignatureException engine not properly initialized
+   * Updates the data to be signed or verified, using the specified array of
+   * bytes, starting at the specified offset.
+   *
+   * @param data the array of bytes.
+   * @param off the offset to start from in the array of bytes.
+   * @param len the number of bytes to use, starting at offset.
+   * @throws SignatureException if this signature object is not initialized
+   * properly.
    */
   public final void update(byte[]data, int off, int len)
     throws SignatureException
@@ -434,11 +516,10 @@ public abstract class Signature extends SignatureSpi
       throw new SignatureException();
   }
 
-  /** 
-     Gets the name of the algorithm currently used.
-     The names of algorithms are usually SHA/DSA or SHA/RSA.
-
-     @return name of algorithm.
+  /**
+   * Returns the name of the algorithm for this signature object.
+   *
+   * @return the name of the algorithm for this signature object.
    */
   public final String getAlgorithm()
   {
@@ -446,9 +527,11 @@ public abstract class Signature extends SignatureSpi
   }
 
   /**
-     Returns a representation of the Signature as a String
-
-     @return a string representing the signature
+   * Returns a string representation of this signature object, providing
+   * information that includes the state of the object and the name of the
+   * algorithm used.
+   *
+   * @return a string representation of this signature object.
    */
   public String toString()
   {
@@ -456,16 +539,22 @@ public abstract class Signature extends SignatureSpi
   }
 
   /**
-     Sets the specified algorithm parameter to the specified value.
-
-     @param param parameter name
-     @param value parameter value
-
-     @throws InvalidParameterException invalid parameter, parameter 
-     already set and cannot set again, a security exception, 
-     etc.
-
-     @deprecated use the other setParameter
+   * Sets the specified algorithm parameter to the specified value. This method
+   * supplies a general-purpose mechanism through which it is possible to set
+   * the various parameters of this object. A parameter may be any settable
+   * parameter for the algorithm, such as a parameter size, or a source of
+   * random bits for signature generation (if appropriate), or an indication of
+   * whether or not to perform a specific but optional computation. A uniform
+   * algorithm-specific naming scheme for each parameter is desirable but left
+   * unspecified at this time.
+   *
+   * @param param the string identifier of the parameter.
+   * @param value the parameter value.
+   * @throws InvalidParameterException if param is an invalid parameter for this
+   * signature algorithm engine, the parameter is already set and cannot be set
+   * again, a security exception occurs, and so on.
+   * @see #getParameter(String)
+   * @deprecated Use setParameter(AlgorithmParameterSpec).
    */
   public final void setParameter(String param, Object value)
     throws InvalidParameterException
@@ -474,17 +563,12 @@ public abstract class Signature extends SignatureSpi
   }
 
   /**
-     Sets the signature engine with the specified 
-     AlgorithmParameterSpec;
-
-     By default this always throws UnsupportedOperationException 
-     if not overridden;
-
-     @param params the parameters
-
-     @throws InvalidParameterException invalid parameter, parameter 
-     already set and cannot set again, a security exception, 
-     etc.
+   * Initializes this signature engine with the specified parameter set.
+   *
+   * @param params the parameters.
+   * @throws InvalidAlgorithmParameterException if the given parameters are
+   * inappropriate for this signature engine.
+   * @see #getParameters()
    */
   public final void setParameter(AlgorithmParameterSpec params)
     throws InvalidAlgorithmParameterException
@@ -493,15 +577,40 @@ public abstract class Signature extends SignatureSpi
   }
 
   /**
-     Gets the value for the specified algorithm parameter.
-
-     @param param parameter name
-
-     @return parameter value
-
-     @throws InvalidParameterException invalid parameter
+   * <p>Returns the parameters used with this signature object.</p>
+   *
+   * <p>The returned parameters may be the same that were used to initialize
+   * this signature, or may contain a combination of default and randomly
+   * generated parameter values used by the underlying signature implementation
+   * if this signature requires algorithm parameters but was not initialized
+   * with any.
+   *
+   * @return the parameters used with this signature, or <code>null</code> if
+   * this signature does not use any parameters.
+   * @see #setParameter(AlgorithmParameterSpec)
+   */
+  public final AlgorithmParameters getParameters()
+  {
+    return engineGetParameters();
+  }
 
-     @deprecated use the other getParameter
+  /**
+   * Gets the value of the specified algorithm parameter. This method supplies
+   * a general-purpose mechanism through which it is possible to get the various
+   * parameters of this object. A parameter may be any settable parameter for
+   * the algorithm, such as a parameter size, or a source of random bits for
+   * signature generation (if appropriate), or an indication of whether or not
+   * to perform a specific but optional computation. A uniform
+   * algorithm-specific naming scheme for each parameter is desirable but left
+   * unspecified at this time.
+   *
+   * @param param the string name of the parameter.
+   * @return the object that represents the parameter value, or null if there
+   * is none.
+   * @throws InvalidParameterException if param is an invalid parameter for this
+   * engine, or another exception occurs while trying to get this parameter.
+   * @see #setParameter(String, Object)
+   * @deprecated
    */
   public final Object getParameter(String param)
     throws InvalidParameterException
@@ -510,12 +619,11 @@ public abstract class Signature extends SignatureSpi
   }
 
   /**
-     Returns a clone if cloneable.
-
-     @return a clone if cloneable.
-
-     @throws CloneNotSupportedException if the implementation does 
-     not support cloning
+   * Returns a clone if the implementation is cloneable.
+   *
+   * @return a clone if the implementation is cloneable.
+   * @throws CloneNotSupportedException if this is called on an implementation
+   * that does not support {@link Cloneable}.
    */
   public Object clone() throws CloneNotSupportedException
   {