libjava/java/security/Signature.java

   1 /* Signature.java --- Signature Class
   2    Copyright (C) 1999, 2002, 2003, 2004  Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package java.security;
  40
  41 import gnu.java.security.Engine;
  42
  43 import java.security.cert.Certificate;
  44 import java.security.cert.X509Certificate;
  45 import java.security.spec.AlgorithmParameterSpec;
  46
  47 /**
  48  * <p>This <code>Signature</code> class is used to provide applications the
  49  * functionality of a digital signature algorithm. Digital signatures are used
  50  * for authentication and integrity assurance of digital data.</p>
  51  *
  52  * <p>The signature algorithm can be, among others, the NIST standard <i>DSS</i>,
  53  * using <i>DSA</i> and <i>SHA-1</i>. The <i>DSA</i> algorithm using the
  54  * <i>SHA-1</i> message digest algorithm can be specified as <code>SHA1withDSA
  55  * </code>. In the case of <i>RSA</i>, there are multiple choices for the
  56  * message digest algorithm, so the signing algorithm could be specified as, for
  57  * example, <code>MD2withRSA</code>, <code>MD5withRSA</code>, or
  58  * <code>SHA1withRSA</code>. The algorithm name must be specified, as there is
  59  * no default.</p>
  60  *
  61  * <p>Like other algorithm-based classes in Java Security, <code>Signature</code>
  62  * provides implementation-independent algorithms, whereby a caller (application
  63  * code) requests a particular signature algorithm and is handed back a properly
  64  * initialized <code>Signature</code> object. It is also possible, if desired,
  65  * to request a particular algorithm from a particular provider. See the
  66  * <code>getInstance()</code> methods.</p>
  67  *
  68  * <p>Thus, there are two ways to request a <code>Signature</code> algorithm
  69  * object: by specifying either just an algorithm name, or both an algorithm
  70  * name and a package provider.</p>
  71  *
  72  * <p>If just an algorithm name is specified, the system will determine if there
  73  * is an implementation of the algorithm requested available in the environment,
  74  * and if there is more than one, if there is a preferred one.</p>
  75  *
  76  * <p>If both an algorithm name and a package provider are specified, the system
  77  * will determine if there is an implementation of the algorithm in the package
  78  * requested, and throw an exception if there is not.</p>
  79  *
  80  * <p>A <code>Signature</code> object can be used to generate and verify digital
  81  * signatures.</p>
  82  *
  83  * <p>There are three phases to the use of a <code>Signature</code> object for
  84  * either signing data or verifying a signature:</p>
  85  *
  86  * <ol>
  87  * <li>Initialization, with either
  88  *     <ul>
  89  *     <li>a public key, which initializes the signature for verification
  90  *         (see <code>initVerify()</code>), or</li>
  91  *     <li>a private key (and optionally a Secure Random Number Generator),
  92  *         which initializes the signature for signing (see
  93  *         {@link #initSign(PrivateKey)} and {@link #initSign(PrivateKey, SecureRandom)}
  94  *         ).</li>
  95  *     </ul></li>
  96  * <li>Updating<br/>
  97  *     Depending on the type of initialization, this will update the bytes to
  98  *     be signed or verified. See the update methods.<br/></li>
  99  * <li>Signing or Verifying a signature on all updated bytes. See the
 100  *     <code>sign()</code> methods and the <code>verify()</code> method.</li>
 101  *  </ol>
 102  *
 103  * <p>Note that this class is abstract and extends from {@link SignatureSpi} for
 104  * historical reasons. Application developers should only take notice of the
 105  * methods defined in this <code>Signature</code> class; all the methods in the
 106  * superclass are intended for cryptographic service providers who wish to
 107  * supply their own implementations of digital signature algorithms.
 108  *
 109  * @author Mark Benvenuto  (ivymccough@worldnet.att.net)
 110  */
 111 public abstract class Signature extends SignatureSpi
 112 {
 113   /** Service name for signatures. */
 114   private static final String SIGNATURE = "Signature";
 115
 116   /**
 117    * Possible <code>state</code> value, signifying that this signature object
 118    * has not yet been initialized.
 119    */
 120   protected static final int UNINITIALIZED = 0;
 121
 122   // Constructor.
 123   // ------------------------------------------------------------------------
 124
 125   /**
 126    * Possible <code>state</code> value, signifying that this signature object
 127    * has been initialized for signing.
 128    */
 129   protected static final int SIGN = 2;
 130
 131   /**
 132    * Possible <code>state</code> value, signifying that this signature object
 133    * has been initialized for verification.
 134    */
 135   protected static final int VERIFY = 3;
 136
 137   /** Current state of this signature object. */
 138   protected int state = UNINITIALIZED;
 139
 140   private String algorithm;
 141   Provider provider;
 142
 143   /**
 144    * Creates a <code>Signature</code> object for the specified algorithm.
 145    *
 146    * @param algorithm the standard string name of the algorithm. See Appendix A
 147    * in the Java Cryptography Architecture API Specification &amp; Reference for
 148    * information about standard algorithm names.
 149    */
 150   protected Signature(String algorithm)
 151   {
 152     this.algorithm = algorithm;
 153     state = UNINITIALIZED;
 154   }
 155
 156   /**
 157    * Generates a <code>Signature</code> object that implements the specified
 158    * digest algorithm. If the default provider package provides an
 159    * implementation of the requested digest algorithm, an instance of
 160    * <code>Signature</code> containing that implementation is returned. If the
 161    * algorithm is not available in the default package, other packages are
 162    * searched.
 163    *
 164    * @param algorithm the standard name of the algorithm requested. See Appendix
 165    * A in the Java Cryptography Architecture API Specification &amp; Reference
 166    * for information about standard algorithm names.
 167    * @return the new Signature object.
 168    * @throws NoSuchAlgorithmException if the algorithm is not available in the
 169    * environment.
 170    */
 171   public static Signature getInstance(String algorithm)
 172     throws NoSuchAlgorithmException
 173   {
 174     Provider[] p = Security.getProviders();
 175     for (int i = 0; i < p.length; i++)
 176       {
 177         try
 178           {
 179             return getInstance(algorithm, p[i]);
 180           }
 181         catch (NoSuchAlgorithmException e)
 182           {
 183             // Ignored.
 184           }
 185       }
 186
 187     throw new NoSuchAlgorithmException(algorithm);
 188   }
 189
 190   /**
 191    * Generates a <code>Signature</code> object implementing the specified
 192    * algorithm, as supplied from the specified provider, if such an algorithm
 193    * is available from the provider.
 194    *
 195    * @param algorithm the name of the algorithm requested. See Appendix A in
 196    * the Java Cryptography Architecture API Specification &amp; Reference for
 197    * information about standard algorithm names.
 198    * @param provider the name of the provider.
 199    * @return the new <code>Signature</code> object.
 200    * @throws NoSuchAlgorithmException if the algorithm is not available in the
 201    * package supplied by the requested provider.
 202    * @throws NoSuchProviderException if the provider is not available in the
 203    * environment.
 204    * @throws IllegalArgumentException if the provider name is <code>null</code>
 205    * or empty.
 206    * @see Provider
 207    */
 208   public static Signature getInstance(String algorithm, String provider)
 209     throws NoSuchAlgorithmException, NoSuchProviderException
 210   {
 211     if (provider == null || provider.length() == 0)
 212       throw new IllegalArgumentException("Illegal provider");
 213
 214     Provider p = Security.getProvider(provider);
 215     if (p == null)
 216       throw new NoSuchProviderException(provider);
 217
 218     return getInstance(algorithm, p);
 219   }
 220
 221   /**
 222    * Generates a <code>Signature</code> object implementing the specified
 223    * algorithm, as supplied from the specified provider, if such an algorithm
 224    * is available from the provider. Note: the provider doesn't have to be
 225    * registered.
 226    *
 227    * @param algorithm the name of the algorithm requested. See Appendix A in
 228    * the Java Cryptography Architecture API Specification &amp; Reference for
 229    * information about standard algorithm names.
 230    * @param provider the provider.
 231    * @return the new <code>Signature</code> object.
 232    * @throws NoSuchAlgorithmException if the <code>algorithm</code> is not
 233    * available in the package supplied by the requested <code>provider</code>.
 234    * @throws IllegalArgumentException if the <code>provider</code> is
 235    * <code>null</code>.
 236    * @since 1.4
 237    * @see Provider
 238    */
 239   public static Signature getInstance(String algorithm, Provider provider)
 240     throws NoSuchAlgorithmException
 241   {
 242     if (provider == null)
 243       throw new IllegalArgumentException("Illegal provider");
 244
 245     Signature result = null;
 246     Object o = null;
 247     try
 248       {
 249         o = Engine.getInstance(SIGNATURE, algorithm, provider);
 250       }
 251     catch (java.lang.reflect.InvocationTargetException ite)
 252       {
 253         throw new NoSuchAlgorithmException(algorithm);
 254       }
 255
 256     if (o instanceof SignatureSpi)
 257       {
 258         result = new DummySignature((SignatureSpi) o, algorithm);
 259       }
 260     else if (o instanceof Signature)
 261       {
 262         result = (Signature) o;
 263         result.algorithm = algorithm;
 264       }
 265     else
 266       {
 267         throw new NoSuchAlgorithmException(algorithm);
 268       }
 269     result.provider = provider;
 270     return result;
 271   }
 272
 273   /**
 274    * Returns the provider of this signature object.
 275    *
 276    * @return the provider of this signature object.
 277    */
 278   public final Provider getProvider()
 279   {
 280     return provider;
 281   }
 282
 283   /**
 284    * Initializes this object for verification. If this method is called again
 285    * with a different argument, it negates the effect of this call.
 286    *
 287    * @param publicKey the public key of the identity whose signature is going
 288    * to be verified.
 289    * @throws InvalidKeyException if the key is invalid.
 290    */
 291   public final void initVerify(PublicKey publicKey) throws InvalidKeyException
 292   {
 293     state = VERIFY;
 294     engineInitVerify(publicKey);
 295   }
 296
 297   /**
 298    * <p>Initializes this object for verification, using the public key from the
 299    * given certificate.</p>
 300    *
 301    * <p>If the certificate is of type <i>X.509</i> and has a <i>key usage</i>
 302    * extension field marked as <i>critical</i>, and the value of the <i>key
 303    * usage</i> extension field implies that the public key in the certificate
 304    * and its corresponding private key are not supposed to be used for digital
 305    * signatures, an {@link InvalidKeyException} is thrown.</p>
 306    *
 307    * @param certificate the certificate of the identity whose signature is
 308    * going to be verified.
 309    * @throws InvalidKeyException if the public key in the certificate is not
 310    * encoded properly or does not include required parameter information or
 311    * cannot be used for digital signature purposes.
 312    */
 313   public final void initVerify(Certificate certificate)
 314     throws InvalidKeyException
 315   {
 316     state = VERIFY;
 317     if (certificate.getType().equals("X509"))
 318       {
 319         X509Certificate cert = (X509Certificate) certificate;
 320         boolean[]array = cert.getKeyUsage();
 321         if (array != null && array[0] == false)
 322           throw new InvalidKeyException(
 323               "KeyUsage of this Certificate indicates it cannot be used for digital signing");
 324       }
 325     this.initVerify(certificate.getPublicKey());
 326   }
 327
 328   /**
 329    * Initialize this object for signing. If this method is called again with a
 330    * different argument, it negates the effect of this call.
 331    *
 332    * @param privateKey the private key of the identity whose signature is going
 333    * to be generated.
 334    * @throws InvalidKeyException if the key is invalid.
 335    */
 336   public final void initSign(PrivateKey privateKey) throws InvalidKeyException
 337   {
 338     state = SIGN;
 339     engineInitSign(privateKey);
 340   }
 341
 342   /**
 343    * Initialize this object for signing. If this method is called again with a
 344    * different argument, it negates the effect of this call.
 345    *
 346    * @param privateKey the private key of the identity whose signature is going
 347    * to be generated.
 348    * @param random the source of randomness for this signature.
 349    * @throws InvalidKeyException if the key is invalid.
 350    */
 351   public final void initSign(PrivateKey privateKey, SecureRandom random)
 352     throws InvalidKeyException
 353   {
 354     state = SIGN;
 355     engineInitSign(privateKey, random);
 356   }
 357
 358   /**
 359    * <p>Returns the signature bytes of all the data updated. The format of the
 360    * signature depends on the underlying signature scheme.</p>
 361    *
 362    * <p>A call to this method resets this signature object to the state it was
 363    * in when previously initialized for signing via a call to
 364    * <code>initSign(PrivateKey)</code>. That is, the object is reset and
 365    * available to generate another signature from the same signer, if desired,
 366    * via new calls to <code>update()</code> and <code>sign()</code>.</p>
 367    *
 368    * @return the signature bytes of the signing operation's result.
 369    * @throws SignatureException if this signature object is not initialized
 370    * properly.
 371    */
 372   public final byte[] sign() throws SignatureException
 373   {
 374     if (state == SIGN)
 375       return engineSign();
 376     else
 377       throw new SignatureException();
 378   }
 379
 380   /**
 381    * <p>Finishes the signature operation and stores the resulting signature
 382    * bytes in the provided buffer <code>outbuf</code>, starting at <code>offset
 383    * </code>. The format of the signature depends on the underlying signature
 384    * scheme.</p>
 385    *
 386    * <p>This signature object is reset to its initial state (the state it was
 387    * in after a call to one of the <code>initSign()</code> methods) and can be
 388    * reused to generate further signatures with the same private key.</p>
 389    *
 390    * @param outbuf buffer for the signature result.
 391    * @param offset offset into outbuf where the signature is stored.
 392    * @param len number of bytes within outbuf allotted for the signature.
 393    * @return the number of bytes placed into outbuf.
 394    * @throws SignatureException if an error occurs or len is less than the
 395    * actual signature length.
 396    * @since 1.2
 397    */
 398   public final int sign(byte[] outbuf, int offset, int len)
 399     throws SignatureException
 400   {
 401     if (state == SIGN)
 402       return engineSign(outbuf, offset, len);
 403     else
 404       throw new SignatureException();
 405   }
 406
 407   /**
 408    * <p>Verifies the passed-in signature.</p>
 409    *
 410    * <p>A call to this method resets this signature object to the state it was
 411    * in when previously initialized for verification via a call to
 412    * <code>initVerify(PublicKey)</code>. That is, the object is reset and
 413    * available to verify another signature from the identity whose public key
 414    * was specified in the call to <code>initVerify()</code>.</p>
 415    *
 416    * @param signature the signature bytes to be verified.
 417    * @return <code>true</code> if the signature was verified, <code>false</code>
 418    * if not.
 419    * @throws SignatureException if this signature object is not initialized
 420    * properly, or the passed-in signature is improperly encoded or of the wrong
 421    * type, etc.
 422    */
 423   public final boolean verify(byte[]signature) throws SignatureException
 424   {
 425     if (state == VERIFY)
 426       return engineVerify(signature);
 427     else
 428       throw new SignatureException();
 429   }
 430
 431   /**
 432    * <p>Verifies the passed-in <code>signature</code> in the specified array of
 433    * bytes, starting at the specified <code>offset</code>.</p>
 434    *
 435    * <p>A call to this method resets this signature object to the state it was
 436    * in when previously initialized for verification via a call to
 437    * <code>initVerify(PublicKey)</code>. That is, the object is reset and
 438    * available to verify another signature from the identity whose public key
 439    * was specified in the call to <code>initVerify()</code>.</p>
 440    *
 441    * @param signature the signature bytes to be verified.
 442    * @param offset the offset to start from in the array of bytes.
 443    * @param length the number of bytes to use, starting at offset.
 444    * @return <code>true</code> if the signature was verified, <code>false</code>
 445    * if not.
 446    * @throws SignatureException if this signature object is not initialized
 447    * properly, or the passed-in <code>signature</code> is improperly encoded or
 448    * of the wrong type, etc.
 449    * @throws IllegalArgumentException if the <code>signature</code> byte array
 450    * is <code>null</code>, or the <code>offset</code> or <code>length</code> is
 451    * less than <code>0</code>, or the sum of the <code>offset</code> and
 452    * <code>length</code> is greater than the length of the <code>signature</code>
 453    * byte array.
 454    */
 455   public final boolean verify(byte[] signature, int offset, int length)
 456     throws SignatureException
 457   {
 458     if (state != VERIFY)
 459       throw new SignatureException("illegal state");
 460
 461     if (signature == null)
 462       throw new IllegalArgumentException("signature is null");
 463     if (offset < 0)
 464       throw new IllegalArgumentException("offset is less than 0");
 465     if (length < 0)
 466       throw new IllegalArgumentException("length is less than 0");
 467     if (offset + length < signature.length)
 468       throw new IllegalArgumentException("range is out of bounds");
 469
 470     return engineVerify(signature, offset, length);
 471   }
 472
 473   /**
 474    * Updates the data to be signed or verified by a byte.
 475    *
 476    * @param b the byte to use for the update.
 477    * @throws SignatureException if this signature object is not initialized
 478    * properly.
 479    */
 480   public final void update(byte b) throws SignatureException
 481   {
 482     if (state != UNINITIALIZED)
 483       engineUpdate(b);
 484     else
 485       throw new SignatureException();
 486   }
 487
 488   /**
 489    * Updates the data to be signed or verified, using the specified array of
 490    * bytes.
 491    *
 492    * @param data the byte array to use for the update.
 493    * @throws SignatureException if this signature object is not initialized
 494    * properly.
 495    */
 496   public final void update(byte[]data) throws SignatureException
 497   {
 498     if (state != UNINITIALIZED)
 499       engineUpdate(data, 0, data.length);
 500     else
 501       throw new SignatureException();
 502   }
 503
 504   /**
 505    * Updates the data to be signed or verified, using the specified array of
 506    * bytes, starting at the specified offset.
 507    *
 508    * @param data the array of bytes.
 509    * @param off the offset to start from in the array of bytes.
 510    * @param len the number of bytes to use, starting at offset.
 511    * @throws SignatureException if this signature object is not initialized
 512    * properly.
 513    */
 514   public final void update(byte[]data, int off, int len)
 515     throws SignatureException
 516   {
 517     if (state != UNINITIALIZED)
 518       engineUpdate(data, off, len);
 519     else
 520       throw new SignatureException();
 521   }
 522
 523   /**
 524    * Returns the name of the algorithm for this signature object.
 525    *
 526    * @return the name of the algorithm for this signature object.
 527    */
 528   public final String getAlgorithm()
 529   {
 530     return algorithm;
 531   }
 532
 533   /**
 534    * Returns a string representation of this signature object, providing
 535    * information that includes the state of the object and the name of the
 536    * algorithm used.
 537    *
 538    * @return a string representation of this signature object.
 539    */
 540   public String toString()
 541   {
 542     return (algorithm + " Signature");
 543   }
 544
 545   /**
 546    * Sets the specified algorithm parameter to the specified value. This method
 547    * supplies a general-purpose mechanism through which it is possible to set
 548    * the various parameters of this object. A parameter may be any settable
 549    * parameter for the algorithm, such as a parameter size, or a source of
 550    * random bits for signature generation (if appropriate), or an indication of
 551    * whether or not to perform a specific but optional computation. A uniform
 552    * algorithm-specific naming scheme for each parameter is desirable but left
 553    * unspecified at this time.
 554    *
 555    * @param param the string identifier of the parameter.
 556    * @param value the parameter value.
 557    * @throws InvalidParameterException if param is an invalid parameter for this
 558    * signature algorithm engine, the parameter is already set and cannot be set
 559    * again, a security exception occurs, and so on.
 560    * @see #getParameter(String)
 561    * @deprecated Use setParameter(AlgorithmParameterSpec).
 562    */
 563   public final void setParameter(String param, Object value)
 564     throws InvalidParameterException
 565   {
 566     engineSetParameter(param, value);
 567   }
 568
 569   /**
 570    * Initializes this signature engine with the specified parameter set.
 571    *
 572    * @param params the parameters.
 573    * @throws InvalidAlgorithmParameterException if the given parameters are
 574    * inappropriate for this signature engine.
 575    * @see #getParameters()
 576    */
 577   public final void setParameter(AlgorithmParameterSpec params)
 578     throws InvalidAlgorithmParameterException
 579   {
 580     engineSetParameter(params);
 581   }
 582
 583   /**
 584    * <p>Returns the parameters used with this signature object.</p>
 585    *
 586    * <p>The returned parameters may be the same that were used to initialize
 587    * this signature, or may contain a combination of default and randomly
 588    * generated parameter values used by the underlying signature implementation
 589    * if this signature requires algorithm parameters but was not initialized
 590    * with any.
 591    *
 592    * @return the parameters used with this signature, or <code>null</code> if
 593    * this signature does not use any parameters.
 594    * @see #setParameter(AlgorithmParameterSpec)
 595    */
 596   public final AlgorithmParameters getParameters()
 597   {
 598     return engineGetParameters();
 599   }
 600
 601   /**
 602    * Gets the value of the specified algorithm parameter. This method supplies
 603    * a general-purpose mechanism through which it is possible to get the various
 604    * parameters of this object. A parameter may be any settable parameter for
 605    * the algorithm, such as a parameter size, or a source of random bits for
 606    * signature generation (if appropriate), or an indication of whether or not
 607    * to perform a specific but optional computation. A uniform
 608    * algorithm-specific naming scheme for each parameter is desirable but left
 609    * unspecified at this time.
 610    *
 611    * @param param the string name of the parameter.
 612    * @return the object that represents the parameter value, or null if there
 613    * is none.
 614    * @throws InvalidParameterException if param is an invalid parameter for this
 615    * engine, or another exception occurs while trying to get this parameter.
 616    * @see #setParameter(String, Object)
 617    * @deprecated
 618    */
 619   public final Object getParameter(String param)
 620     throws InvalidParameterException
 621   {
 622     return engineGetParameter(param);
 623   }
 624
 625   /**
 626    * Returns a clone if the implementation is cloneable.
 627    *
 628    * @return a clone if the implementation is cloneable.
 629    * @throws CloneNotSupportedException if this is called on an implementation
 630    * that does not support {@link Cloneable}.
 631    */
 632   public Object clone() throws CloneNotSupportedException
 633   {
 634     return super.clone();
 635   }
 636 }