001: /*
002: * Copyright 1996-2006 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025:
026: package java.security;
027:
028: import java.util.*;
029: import java.lang.*;
030: import java.io.IOException;
031: import java.io.ByteArrayOutputStream;
032: import java.io.PrintStream;
033: import java.io.InputStream;
034: import java.io.ByteArrayInputStream;
035:
036: import java.nio.ByteBuffer;
037:
038: /**
039: * This MessageDigest class provides applications the functionality of a
040: * message digest algorithm, such as MD5 or SHA.
041: * Message digests are secure one-way hash functions that take arbitrary-sized
042: * data and output a fixed-length hash value.
043: *
044: * <p>A MessageDigest object starts out initialized. The data is
045: * processed through it using the {@link #update(byte) update}
046: * methods. At any point {@link #reset() reset} can be called
047: * to reset the digest. Once all the data to be updated has been
048: * updated, one of the {@link #digest() digest} methods should
049: * be called to complete the hash computation.
050: *
051: * <p>The <code>digest</code> method can be called once for a given number
052: * of updates. After <code>digest</code> has been called, the MessageDigest
053: * object is reset to its initialized state.
054: *
055: * <p>Implementations are free to implement the Cloneable interface.
056: * Client applications can test cloneability by attempting cloning
057: * and catching the CloneNotSupportedException: <p>
058: *
059: * <pre>
060: * MessageDigest md = MessageDigest.getInstance("SHA");
061: *
062: * try {
063: * md.update(toChapter1);
064: * MessageDigest tc1 = md.clone();
065: * byte[] toChapter1Digest = tc1.digest();
066: * md.update(toChapter2);
067: * ...etc.
068: * } catch (CloneNotSupportedException cnse) {
069: * throw new DigestException("couldn't make digest of partial content");
070: * }
071: * </pre>
072: *
073: * <p>Note that if a given implementation is not cloneable, it is
074: * still possible to compute intermediate digests by instantiating
075: * several instances, if the number of digests is known in advance.
076: *
077: * <p>Note that this class is abstract and extends from
078: * <code>MessageDigestSpi</code> for historical reasons.
079: * Application developers should only take notice of the methods defined in
080: * this <code>MessageDigest</code> class; all the methods in
081: * the superclass are intended for cryptographic service providers who wish to
082: * supply their own implementations of message digest algorithms.
083: *
084: * @author Benjamin Renaud
085: *
086: * @version 1.87, 05/05/07
087: *
088: * @see DigestInputStream
089: * @see DigestOutputStream
090: */
091:
092: public abstract class MessageDigest extends MessageDigestSpi {
093:
094: private String algorithm;
095:
096: // The state of this digest
097: private static final int INITIAL = 0;
098: private static final int IN_PROGRESS = 1;
099: private int state = INITIAL;
100:
101: // The provider
102: private Provider provider;
103:
104: /**
105: * Creates a message digest with the specified algorithm name.
106: *
107: * @param algorithm the standard name of the digest algorithm.
108: * See Appendix A in the <a href=
109: * "../../../technotes/guides/security/crypto/CryptoSpec.html#AppA">
110: * Java Cryptography Architecture API Specification & Reference </a>
111: * for information about standard algorithm names.
112: */
113: protected MessageDigest(String algorithm) {
114: this .algorithm = algorithm;
115: }
116:
117: /**
118: * Returns a MessageDigest object that implements the specified digest
119: * algorithm.
120: *
121: * <p> This method traverses the list of registered security Providers,
122: * starting with the most preferred Provider.
123: * A new MessageDigest object encapsulating the
124: * MessageDigestSpi implementation from the first
125: * Provider that supports the specified algorithm is returned.
126: *
127: * <p> Note that the list of registered providers may be retrieved via
128: * the {@link Security#getProviders() Security.getProviders()} method.
129: *
130: * @param algorithm the name of the algorithm requested.
131: * See Appendix A in the <a href=
132: * "../../../technotes/guides/security/crypto/CryptoSpec.html#AppA">
133: * Java Cryptography Architecture API Specification & Reference </a>
134: * for information about standard algorithm names.
135: *
136: * @return a Message Digest object that implements the specified algorithm.
137: *
138: * @exception NoSuchAlgorithmException if no Provider supports a
139: * MessageDigestSpi implementation for the
140: * specified algorithm.
141: *
142: * @see Provider
143: */
144: public static MessageDigest getInstance(String algorithm)
145: throws NoSuchAlgorithmException {
146: try {
147: Object[] objs = Security.getImpl(algorithm,
148: "MessageDigest", (String) null);
149: if (objs[0] instanceof MessageDigest) {
150: MessageDigest md = (MessageDigest) objs[0];
151: md.provider = (Provider) objs[1];
152: return md;
153: } else {
154: MessageDigest delegate = new Delegate(
155: (MessageDigestSpi) objs[0], algorithm);
156: delegate.provider = (Provider) objs[1];
157: return delegate;
158: }
159: } catch (NoSuchProviderException e) {
160: throw new NoSuchAlgorithmException(algorithm + " not found");
161: }
162: }
163:
164: /**
165: * Returns a MessageDigest object that implements the specified digest
166: * algorithm.
167: *
168: * <p> A new MessageDigest object encapsulating the
169: * MessageDigestSpi implementation from the specified provider
170: * is returned. The specified provider must be registered
171: * in the security provider list.
172: *
173: * <p> Note that the list of registered providers may be retrieved via
174: * the {@link Security#getProviders() Security.getProviders()} method.
175: *
176: * @param algorithm the name of the algorithm requested.
177: * See Appendix A in the <a href=
178: * "../../../technotes/guides/security/crypto/CryptoSpec.html#AppA">
179: * Java Cryptography Architecture API Specification & Reference </a>
180: * for information about standard algorithm names.
181: *
182: * @param provider the name of the provider.
183: *
184: * @return a MessageDigest object that implements the specified algorithm.
185: *
186: * @exception NoSuchAlgorithmException if a MessageDigestSpi
187: * implementation for the specified algorithm is not
188: * available from the specified provider.
189: *
190: * @exception NoSuchProviderException if the specified provider is not
191: * registered in the security provider list.
192: *
193: * @exception IllegalArgumentException if the provider name is null
194: * or empty.
195: *
196: * @see Provider
197: */
198: public static MessageDigest getInstance(String algorithm,
199: String provider) throws NoSuchAlgorithmException,
200: NoSuchProviderException {
201: if (provider == null || provider.length() == 0)
202: throw new IllegalArgumentException("missing provider");
203: Object[] objs = Security.getImpl(algorithm, "MessageDigest",
204: provider);
205: if (objs[0] instanceof MessageDigest) {
206: MessageDigest md = (MessageDigest) objs[0];
207: md.provider = (Provider) objs[1];
208: return md;
209: } else {
210: MessageDigest delegate = new Delegate(
211: (MessageDigestSpi) objs[0], algorithm);
212: delegate.provider = (Provider) objs[1];
213: return delegate;
214: }
215: }
216:
217: /**
218: * Returns a MessageDigest object that implements the specified digest
219: * algorithm.
220: *
221: * <p> A new MessageDigest object encapsulating the
222: * MessageDigestSpi implementation from the specified Provider
223: * object is returned. Note that the specified Provider object
224: * does not have to be registered in the provider list.
225: *
226: * @param algorithm the name of the algorithm requested.
227: * See Appendix A in the <a href=
228: * "../../../technotes/guides/security/crypto/CryptoSpec.html#AppA">
229: * Java Cryptography Architecture API Specification & Reference </a>
230: * for information about standard algorithm names.
231: *
232: * @param provider the provider.
233: *
234: * @return a MessageDigest object that implements the specified algorithm.
235: *
236: * @exception NoSuchAlgorithmException if a MessageDigestSpi
237: * implementation for the specified algorithm is not available
238: * from the specified Provider object.
239: *
240: * @exception IllegalArgumentException if the specified provider is null.
241: *
242: * @see Provider
243: *
244: * @since 1.4
245: */
246: public static MessageDigest getInstance(String algorithm,
247: Provider provider) throws NoSuchAlgorithmException {
248: if (provider == null)
249: throw new IllegalArgumentException("missing provider");
250: Object[] objs = Security.getImpl(algorithm, "MessageDigest",
251: provider);
252: if (objs[0] instanceof MessageDigest) {
253: MessageDigest md = (MessageDigest) objs[0];
254: md.provider = (Provider) objs[1];
255: return md;
256: } else {
257: MessageDigest delegate = new Delegate(
258: (MessageDigestSpi) objs[0], algorithm);
259: delegate.provider = (Provider) objs[1];
260: return delegate;
261: }
262: }
263:
264: /**
265: * Returns the provider of this message digest object.
266: *
267: * @return the provider of this message digest object
268: */
269: public final Provider getProvider() {
270: return this .provider;
271: }
272:
273: /**
274: * Updates the digest using the specified byte.
275: *
276: * @param input the byte with which to update the digest.
277: */
278: public void update(byte input) {
279: engineUpdate(input);
280: state = IN_PROGRESS;
281: }
282:
283: /**
284: * Updates the digest using the specified array of bytes, starting
285: * at the specified offset.
286: *
287: * @param input the array of bytes.
288: *
289: * @param offset the offset to start from in the array of bytes.
290: *
291: * @param len the number of bytes to use, starting at
292: * <code>offset</code>.
293: */
294: public void update(byte[] input, int offset, int len) {
295: if (input == null) {
296: throw new IllegalArgumentException("No input buffer given");
297: }
298: if (input.length - offset < len) {
299: throw new IllegalArgumentException("Input buffer too short");
300: }
301: engineUpdate(input, offset, len);
302: state = IN_PROGRESS;
303: }
304:
305: /**
306: * Updates the digest using the specified array of bytes.
307: *
308: * @param input the array of bytes.
309: */
310: public void update(byte[] input) {
311: engineUpdate(input, 0, input.length);
312: state = IN_PROGRESS;
313: }
314:
315: /**
316: * Update the digest using the specified ByteBuffer. The digest is
317: * updated using the <code>input.remaining()</code> bytes starting
318: * at <code>input.position()</code>.
319: * Upon return, the buffer's position will be equal to its limit;
320: * its limit will not have changed.
321: *
322: * @param input the ByteBuffer
323: * @since 1.5
324: */
325: public final void update(ByteBuffer input) {
326: if (input == null) {
327: throw new NullPointerException();
328: }
329: engineUpdate(input);
330: state = IN_PROGRESS;
331: }
332:
333: /**
334: * Completes the hash computation by performing final operations
335: * such as padding. The digest is reset after this call is made.
336: *
337: * @return the array of bytes for the resulting hash value.
338: */
339: public byte[] digest() {
340: /* Resetting is the responsibility of implementors. */
341: byte[] result = engineDigest();
342: state = INITIAL;
343: return result;
344: }
345:
346: /**
347: * Completes the hash computation by performing final operations
348: * such as padding. The digest is reset after this call is made.
349: *
350: * @param buf output buffer for the computed digest
351: *
352: * @param offset offset into the output buffer to begin storing the digest
353: *
354: * @param len number of bytes within buf allotted for the digest
355: *
356: * @return the number of bytes placed into <code>buf</code>
357: *
358: * @exception DigestException if an error occurs.
359: */
360: public int digest(byte[] buf, int offset, int len)
361: throws DigestException {
362: if (buf == null) {
363: throw new IllegalArgumentException("No output buffer given");
364: }
365: if (buf.length - offset < len) {
366: throw new IllegalArgumentException(
367: "Output buffer too small for specified offset and length");
368: }
369: int numBytes = engineDigest(buf, offset, len);
370: state = INITIAL;
371: return numBytes;
372: }
373:
374: /**
375: * Performs a final update on the digest using the specified array
376: * of bytes, then completes the digest computation. That is, this
377: * method first calls {@link #update(byte[]) update(input)},
378: * passing the <i>input</i> array to the <code>update</code> method,
379: * then calls {@link #digest() digest()}.
380: *
381: * @param input the input to be updated before the digest is
382: * completed.
383: *
384: * @return the array of bytes for the resulting hash value.
385: */
386: public byte[] digest(byte[] input) {
387: update(input);
388: return digest();
389: }
390:
391: /**
392: * Returns a string representation of this message digest object.
393: */
394: public String toString() {
395: ByteArrayOutputStream baos = new ByteArrayOutputStream();
396: PrintStream p = new PrintStream(baos);
397: p.print(algorithm + " Message Digest from "
398: + provider.getName() + ", ");
399: switch (state) {
400: case INITIAL:
401: p.print("<initialized>");
402: break;
403: case IN_PROGRESS:
404: p.print("<in progress>");
405: break;
406: }
407: p.println();
408: return (baos.toString());
409: }
410:
411: /**
412: * Compares two digests for equality. Does a simple byte compare.
413: *
414: * @param digesta one of the digests to compare.
415: *
416: * @param digestb the other digest to compare.
417: *
418: * @return true if the digests are equal, false otherwise.
419: */
420: public static boolean isEqual(byte digesta[], byte digestb[]) {
421: if (digesta.length != digestb.length)
422: return false;
423:
424: for (int i = 0; i < digesta.length; i++) {
425: if (digesta[i] != digestb[i]) {
426: return false;
427: }
428: }
429: return true;
430: }
431:
432: /**
433: * Resets the digest for further use.
434: */
435: public void reset() {
436: engineReset();
437: state = INITIAL;
438: }
439:
440: /**
441: * Returns a string that identifies the algorithm, independent of
442: * implementation details. The name should be a standard
443: * Java Security name (such as "SHA", "MD5", and so on).
444: * See Appendix A in the <a href=
445: * "../../../technotes/guides/security/crypto/CryptoSpec.html#AppA">
446: * Java Cryptography Architecture API Specification & Reference </a>
447: * for information about standard algorithm names.
448: *
449: * @return the name of the algorithm
450: */
451: public final String getAlgorithm() {
452: return this .algorithm;
453: }
454:
455: /**
456: * Returns the length of the digest in bytes, or 0 if this operation is
457: * not supported by the provider and the implementation is not cloneable.
458: *
459: * @return the digest length in bytes, or 0 if this operation is not
460: * supported by the provider and the implementation is not cloneable.
461: *
462: * @since 1.2
463: */
464: public final int getDigestLength() {
465: int digestLen = engineGetDigestLength();
466: if (digestLen == 0) {
467: try {
468: MessageDigest md = (MessageDigest) clone();
469: byte[] digest = md.digest();
470: return digest.length;
471: } catch (CloneNotSupportedException e) {
472: return digestLen;
473: }
474: }
475: return digestLen;
476: }
477:
478: /**
479: * Returns a clone if the implementation is cloneable.
480: *
481: * @return a clone if the implementation is cloneable.
482: *
483: * @exception CloneNotSupportedException if this is called on an
484: * implementation that does not support <code>Cloneable</code>.
485: */
486: public Object clone() throws CloneNotSupportedException {
487: if (this instanceof Cloneable) {
488: return super .clone();
489: } else {
490: throw new CloneNotSupportedException();
491: }
492: }
493:
494: /*
495: * The following class allows providers to extend from MessageDigestSpi
496: * rather than from MessageDigest. It represents a MessageDigest with an
497: * encapsulated, provider-supplied SPI object (of type MessageDigestSpi).
498: * If the provider implementation is an instance of MessageDigestSpi,
499: * the getInstance() methods above return an instance of this class, with
500: * the SPI object encapsulated.
501: *
502: * Note: All SPI methods from the original MessageDigest class have been
503: * moved up the hierarchy into a new class (MessageDigestSpi), which has
504: * been interposed in the hierarchy between the API (MessageDigest)
505: * and its original parent (Object).
506: */
507:
508: static class Delegate extends MessageDigest {
509:
510: // The provider implementation (delegate)
511: private MessageDigestSpi digestSpi;
512:
513: // constructor
514: public Delegate(MessageDigestSpi digestSpi, String algorithm) {
515: super (algorithm);
516: this .digestSpi = digestSpi;
517: }
518:
519: /**
520: * Returns a clone if the delegate is cloneable.
521: *
522: * @return a clone if the delegate is cloneable.
523: *
524: * @exception CloneNotSupportedException if this is called on a
525: * delegate that does not support <code>Cloneable</code>.
526: */
527: public Object clone() throws CloneNotSupportedException {
528: if (digestSpi instanceof Cloneable) {
529: MessageDigestSpi digestSpiClone = (MessageDigestSpi) digestSpi
530: .clone();
531: // Because 'algorithm', 'provider', and 'state' are private
532: // members of our supertype, we must perform a cast to
533: // access them.
534: MessageDigest that = new Delegate(digestSpiClone,
535: ((MessageDigest) this ).algorithm);
536: that.provider = ((MessageDigest) this ).provider;
537: that.state = ((MessageDigest) this ).state;
538: return that;
539: } else {
540: throw new CloneNotSupportedException();
541: }
542: }
543:
544: protected int engineGetDigestLength() {
545: return digestSpi.engineGetDigestLength();
546: }
547:
548: protected void engineUpdate(byte input) {
549: digestSpi.engineUpdate(input);
550: }
551:
552: protected void engineUpdate(byte[] input, int offset, int len) {
553: digestSpi.engineUpdate(input, offset, len);
554: }
555:
556: protected void engineUpdate(ByteBuffer input) {
557: digestSpi.engineUpdate(input);
558: }
559:
560: protected byte[] engineDigest() {
561: return digestSpi.engineDigest();
562: }
563:
564: protected int engineDigest(byte[] buf, int offset, int len)
565: throws DigestException {
566: return digestSpi.engineDigest(buf, offset, len);
567: }
568:
569: protected void engineReset() {
570: digestSpi.engineReset();
571: }
572: }
573: }
|
