| Frames | No Frames |
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., 51 Franklin Street, Fifth Floor, Boston, MA 19: 02110-1301 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.lang.CPStringBuilder; 42: 43: import gnu.java.security.Engine; 44: 45: import java.lang.reflect.InvocationTargetException; 46: import java.nio.ByteBuffer; 47: import java.security.cert.Certificate; 48: import java.security.cert.X509Certificate; 49: import java.security.spec.AlgorithmParameterSpec; 50: 51: /** 52: * <code>Signature</code> is used to provide an interface to digital signature 53: * algorithms. Digital signatures provide authentication and data integrity of 54: * digital data. 55: * 56: * <p>The GNU provider provides the NIST standard DSA which uses DSA and SHA-1. 57: * It can be specified by SHA/DSA, SHA-1/DSA or its OID. If the RSA signature 58: * algorithm is provided then it could be MD2/RSA. MD5/RSA, or SHA-1/RSA. The 59: * algorithm must be specified because there is no default.</p> 60: * 61: * <p>Signature provides implementation-independent algorithms which are 62: * requested by the user through the <code>getInstance()<?code> methods. It can 63: * be requested by specifying just the algorithm name or by specifying both the 64: * algorithm name and provider name.</p> 65: * 66: * <p>The three phases of using <code>Signature</code> are:</p> 67: * 68: * <ol> 69: * <li>Initializing: 70: * <ul> 71: * <li>It must be initialized with a private key for signing.</li> 72: * <li>It must be initialized with a public key for verifying.</li> 73: * </li> 74: * 75: * <li>Updating: 76: * <p>Update the bytes for signing or verifying with calls to update.</p> 77: * </li> 78: * 79: * <li>Signing or Verify the signature on the currently stored bytes by 80: * calling sign or verify.</li> 81: * </ol> 82: * 83: * @author Mark Benvenuto (ivymccough@worldnet.att.net) 84: */ 85: public abstract class Signature extends SignatureSpi 86: { 87: /** Service name for signatures. */ 88: private static final String SIGNATURE = "Signature"; 89: 90: /** 91: * Possible state value which signifies that this instance has not yet been 92: * initialized. 93: */ 94: protected static final int UNINITIALIZED = 0; 95: 96: /** 97: * Possible state value which signifies that this instance has been 98: * initialized for signing purposes. 99: */ 100: protected static final int SIGN = 2; 101: 102: /** 103: * Possible state value which signifies that this instance has been 104: * initialized for verification purposes. 105: */ 106: protected static final int VERIFY = 3; 107: 108: /** Current sate of this instance. */ 109: protected int state = UNINITIALIZED; 110: 111: private String algorithm; 112: Provider provider; 113: 114: // Constructor. 115: // ------------------------------------------------------------------------ 116: 117: /** 118: * Constructs a new <code>Signature</code> instance for a designated digital 119: * signature algorithm. 120: * 121: * @param algorithm 122: * the algorithm to use. 123: */ 124: protected Signature(String algorithm) 125: { 126: this.algorithm = algorithm; 127: state = UNINITIALIZED; 128: } 129: 130: /** 131: * Returns an instance of <code>Signature</code> representing the specified 132: * signature. 133: * 134: * @param algorithm the algorithm to use. 135: * @return a new instance repesenting the desired algorithm. 136: * @throws NoSuchAlgorithmException if the algorithm is not implemented by any 137: * provider. 138: * @throws IllegalArgumentException if <code>algorithm</code> is 139: * <code>null</code> or is an empty string. 140: */ 141: public static Signature getInstance(String algorithm) 142: throws NoSuchAlgorithmException 143: { 144: Provider[] p = Security.getProviders(); 145: NoSuchAlgorithmException lastException = null; 146: for (int i = 0; i < p.length; i++) 147: try 148: { 149: return getInstance(algorithm, p[i]); 150: } 151: catch (NoSuchAlgorithmException x) 152: { 153: lastException = x; 154: } 155: if (lastException != null) 156: throw lastException; 157: throw new NoSuchAlgorithmException(algorithm); 158: } 159: 160: /** 161: * Returns an instance of <code>Signature</code> representing the specified 162: * signature from the named provider. 163: * 164: * @param algorithm the algorithm to use. 165: * @param provider the name of the provider to use. 166: * @return a new instance repesenting the desired algorithm. 167: * @throws NoSuchProviderException if the named provider was not found. 168: * @throws NoSuchAlgorithmException if the algorithm is not implemented by the 169: * named provider. 170: * @throws IllegalArgumentException if either <code>algorithm</code> or 171: * <code>provider</code> is <code>null</code> or empty. 172: */ 173: public static Signature getInstance(String algorithm, String provider) 174: throws NoSuchAlgorithmException, NoSuchProviderException 175: { 176: if (provider == null) 177: throw new IllegalArgumentException("provider MUST NOT be null"); 178: provider = provider.trim(); 179: if (provider.length() == 0) 180: throw new IllegalArgumentException("provider MUST NOT be empty"); 181: Provider p = Security.getProvider(provider); 182: if (p == null) 183: throw new NoSuchProviderException(provider); 184: return getInstance(algorithm, p); 185: } 186: 187: /** 188: * Returns an instance of <code>Signature</code> representing the specified 189: * signature from the specified {@link Provider}. 190: * 191: * @param algorithm the algorithm to use. 192: * @param provider the {@link Provider} to use. 193: * @return a new instance repesenting the desired algorithm. 194: * @throws NoSuchAlgorithmException if the algorithm is not implemented by the 195: * {@link Provider}. 196: * @throws IllegalArgumentException if either <code>algorithm</code> or 197: * <code>provider</code> is <code>null</code>, or if 198: * <code>algorithm</code> is an empty string. 199: */ 200: public static Signature getInstance(String algorithm, Provider provider) 201: throws NoSuchAlgorithmException 202: { 203: CPStringBuilder sb = new CPStringBuilder("Signature algorithm [") 204: .append(algorithm).append("] from provider[") 205: .append(provider).append("] "); 206: Object o; 207: try 208: { 209: o = Engine.getInstance(SIGNATURE, algorithm, provider); 210: } 211: catch (InvocationTargetException x) 212: { 213: Throwable cause = x.getCause(); 214: if (cause instanceof NoSuchAlgorithmException) 215: throw (NoSuchAlgorithmException) cause; 216: if (cause == null) 217: cause = x; 218: sb.append("could not be created"); 219: NoSuchAlgorithmException y = new NoSuchAlgorithmException(sb.toString()); 220: y.initCause(cause); 221: throw y; 222: } 223: Signature result; 224: if (o instanceof SignatureSpi) 225: result = new DummySignature((SignatureSpi) o, algorithm); 226: else if (o instanceof Signature) 227: { 228: result = (Signature) o; 229: result.algorithm = algorithm; 230: } 231: else 232: { 233: sb.append("is of an unexpected Type: ").append(o.getClass().getName()); 234: throw new NoSuchAlgorithmException(sb.toString()); 235: } 236: result.provider = provider; 237: return result; 238: } 239: 240: /** 241: * Returns the {@link Provider} of this instance. 242: * 243: * @return the {@link Provider} of this instance. 244: */ 245: public final Provider getProvider() 246: { 247: return provider; 248: } 249: 250: /** 251: * Initializes this instance with the public key for verification purposes. 252: * 253: * @param publicKey 254: * the public key to verify with. 255: * @throws InvalidKeyException 256: * if the key is invalid. 257: */ 258: public final void initVerify(PublicKey publicKey) throws InvalidKeyException 259: { 260: state = VERIFY; 261: engineInitVerify(publicKey); 262: } 263: 264: /** 265: * Verify a signature with a designated {@link Certificate}. This is a FIPS 266: * 140-1 compatible method since it verifies a signature with a certificate. 267: * 268: * <p>If the {@link Certificate} is an X.509 one, has a <i>KeyUsage</i> 269: * parameter and that parameter indicates this key is not to be used for 270: * signing then an exception is thrown.</p> 271: * 272: * @param certificate 273: * a {@link Certificate} containing a public key to verify with. 274: * @throws InvalidKeyException if the key is invalid. 275: */ 276: public final void initVerify(Certificate certificate) 277: throws InvalidKeyException 278: { 279: state = VERIFY; 280: if (certificate.getType().equals("X509")) 281: { 282: X509Certificate cert = (X509Certificate) certificate; 283: boolean[]array = cert.getKeyUsage(); 284: if (array != null && array[0] == false) 285: throw new InvalidKeyException( 286: "KeyUsage of this Certificate indicates it cannot be used for digital signing"); 287: } 288: this.initVerify(certificate.getPublicKey()); 289: } 290: 291: /** 292: * Initializes this class with the private key for signing purposes. 293: * 294: * @param privateKey 295: * the private key to sign with. 296: * @throws InvalidKeyException 297: * if the key is invalid. 298: */ 299: public final void initSign(PrivateKey privateKey) throws InvalidKeyException 300: { 301: state = SIGN; 302: engineInitSign(privateKey); 303: } 304: 305: /** 306: * Initializes this class with the private key and source of randomness for 307: * signing purposes. 308: * 309: * @param privateKey 310: * the private key to sign with. 311: * @param random 312: * the {@link SecureRandom} to use. 313: * @throws InvalidKeyException 314: * if the key is invalid. 315: */ 316: public final void initSign(PrivateKey privateKey, SecureRandom random) 317: throws InvalidKeyException 318: { 319: state = SIGN; 320: engineInitSign(privateKey, random); 321: } 322: 323: /** 324: * Returns the signature bytes of all the data fed to this instance. The 325: * format of the output depends on the underlying signature algorithm. 326: * 327: * @return the signature bytes. 328: * @throws SignatureException 329: * if the engine is not properly initialized. 330: */ 331: public final byte[] sign() throws SignatureException 332: { 333: if (state == SIGN) 334: return engineSign(); 335: else 336: throw new SignatureException(); 337: } 338: 339: /** 340: * Generates signature bytes of all the data fed to this instance and stores 341: * it in the designated array. The format of the result depends on the 342: * underlying signature algorithm. 343: * 344: * <p>After calling this method, the instance is reset to its initial state 345: * and can then be used to generate additional signatures.</p> 346: * 347: * <p><b>IMPLEMENTATION NOTE:</b> Neither this method nor the GNU provider 348: * will return partial digests. If <code>len</code> is less than the 349: * signature length, this method will throw a {@link SignatureException}. If 350: * it is greater than or equal then it is ignored.</p> 351: * 352: * @param outbuf 353: * array of bytes of where to store the resulting signature bytes. 354: * @param offset 355: * the offset to start at in the array. 356: * @param len 357: * the number of the bytes to use in the array. 358: * @return the real number of bytes used. 359: * @throws SignatureException 360: * if the engine is not properly initialized. 361: * @since 1.2 362: */ 363: public final int sign(byte[] outbuf, int offset, int len) 364: throws SignatureException 365: { 366: if (state == SIGN) 367: return engineSign(outbuf, offset, len); 368: else 369: throw new SignatureException(); 370: } 371: 372: /** 373: * Verifies a designated signature. 374: * 375: * @param signature 376: * the signature bytes to verify. 377: * @return <code>true</code> if verified, <code>false</code> otherwise. 378: * @throws SignatureException 379: * if the engine is not properly initialized or the signature does 380: * not check. 381: */ 382: public final boolean verify(byte[]signature) throws SignatureException 383: { 384: if (state == VERIFY) 385: return engineVerify(signature); 386: else 387: throw new SignatureException(); 388: } 389: 390: /** 391: * Verifies a designated signature. 392: * 393: * @param signature 394: * the signature bytes to verify. 395: * @param offset 396: * the offset to start at in the array. 397: * @param length 398: * the number of the bytes to use from the array. 399: * @return <code>true</code> if verified, <code>false</code> otherwise. 400: * @throws IllegalArgumentException 401: * if the <code>signature</code> byte array is <code>null</code>, 402: * or the <code>offset</code> or <code>length</code> is less 403: * than <code>0</code>, or the sum of the <code>offset</code> 404: * and <code>length</code> is greater than the length of the 405: * <code>signature</code> byte array. 406: * @throws SignatureException 407: * if the engine is not properly initialized or the signature does 408: * not check. 409: */ 410: public final boolean verify(byte[] signature, int offset, int length) 411: throws SignatureException 412: { 413: if (state != VERIFY) 414: throw new SignatureException("illegal state"); 415: 416: if (signature == null) 417: throw new IllegalArgumentException("signature is null"); 418: if (offset < 0) 419: throw new IllegalArgumentException("offset is less than 0"); 420: if (length < 0) 421: throw new IllegalArgumentException("length is less than 0"); 422: if (offset + length < signature.length) 423: throw new IllegalArgumentException("range is out of bounds"); 424: 425: return engineVerify(signature, offset, length); 426: } 427: 428: /** 429: * Updates the data to be signed or verified with the specified byte. 430: * 431: * @param b 432: * the byte to update with. 433: * @throws SignatureException 434: * if the engine is not properly initialized. 435: */ 436: public final void update(byte b) throws SignatureException 437: { 438: if (state != UNINITIALIZED) 439: engineUpdate(b); 440: else 441: throw new SignatureException(); 442: } 443: 444: /** 445: * Updates the data to be signed or verified with the specified bytes. 446: * 447: * @param data 448: * the array of bytes to use. 449: * @throws SignatureException 450: * if the engine is not properly initialized. 451: */ 452: public final void update(byte[]data) throws SignatureException 453: { 454: if (state != UNINITIALIZED) 455: engineUpdate(data, 0, data.length); 456: else 457: throw new SignatureException(); 458: } 459: 460: /** 461: * Updates the data to be signed or verified with the specified bytes. 462: * 463: * @param data 464: * an array of bytes to use. 465: * @param off 466: * the offset to start at in the array. 467: * @param len 468: * the number of bytes to use from the array. 469: * @throws SignatureException 470: * if the engine is not properly initialized. 471: */ 472: public final void update(byte[]data, int off, int len) 473: throws SignatureException 474: { 475: if (state != UNINITIALIZED) 476: engineUpdate(data, off, len); 477: else 478: throw new SignatureException(); 479: } 480: 481: /** 482: * Update this signature with the {@link java.nio.Buffer#remaining()} 483: * bytes of the input buffer. 484: * 485: * @param input The input buffer. 486: * @throws SignatureException If this instance was not properly 487: * initialized. 488: */ 489: public final void update(ByteBuffer input) throws SignatureException 490: { 491: if (state != UNINITIALIZED) 492: engineUpdate(input); 493: else 494: throw new SignatureException("not initialized"); 495: } 496: 497: /** 498: * Returns the name of the algorithm currently used. The names of algorithms 499: * are usually SHA/DSA or SHA/RSA. 500: * 501: * @return name of algorithm. 502: */ 503: public final String getAlgorithm() 504: { 505: return algorithm; 506: } 507: 508: /** 509: * Returns a rstring representation of this instance. 510: * 511: * @return a rstring representation of this instance. 512: */ 513: public String toString() 514: { 515: return (algorithm + " Signature"); 516: } 517: 518: /** 519: * Sets the specified algorithm parameter to the specified value. 520: * 521: * @param param 522: * the parameter name. 523: * @param value 524: * the parameter value. 525: * @throws InvalidParameterException 526: * if the parameter is invalid, the parameter is already set and 527: * can not be changed, a security exception occured, etc. 528: * @deprecated use the other setParameter 529: */ 530: public final void setParameter(String param, Object value) 531: throws InvalidParameterException 532: { 533: engineSetParameter(param, value); 534: } 535: 536: /** 537: * Sets the signature engine with the specified {@link AlgorithmParameterSpec}. 538: * 539: * <p>By default, and unless overriden by the concrete SPI, this method always 540: * throws an {@link UnsupportedOperationException}.</p> 541: * 542: * @param params 543: * the parameters to use for intializing this instance. 544: * @throws InvalidParameterException 545: * if the parameter is invalid, the parameter is already set and 546: * cannot be changed, a security exception occured, etc. 547: */ 548: public final void setParameter(AlgorithmParameterSpec params) 549: throws InvalidAlgorithmParameterException 550: { 551: engineSetParameter(params); 552: } 553: 554: /** 555: * Return the parameters of the algorithm used in this instance as an 556: * {@link AlgorithmParameters}. 557: * 558: * @return the parameters used with this instance, or <code>null</code> if 559: * this instance does not use any parameters. 560: */ 561: public final AlgorithmParameters getParameters() 562: { 563: return engineGetParameters(); 564: } 565: 566: /** 567: * Returns the value for the specified algorithm parameter. 568: * 569: * @param param 570: * the parameter name. 571: * @return the parameter value. 572: * @throws InvalidParameterException 573: * if the parameter is invalid. 574: * @deprecated use the other getParameter 575: */ 576: public final Object getParameter(String param) 577: throws InvalidParameterException 578: { 579: return engineGetParameter(param); 580: } 581: 582: /** 583: * Returns a clone of this instance. 584: * 585: * @return a clone of this instace. 586: * @throws CloneNotSupportedException 587: * if the implementation does not support cloning. 588: */ 589: public Object clone() throws CloneNotSupportedException 590: { 591: return super.clone(); 592: } 593: }