1 /*
2 * Copyright (c) 1996, 2015, Oracle and/or its affiliates. All rights reserved.
3 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
4 *
5 *
6 *
7 *
8 *
9 *
10 *
11 *
12 *
13 *
14 *
15 *
16 *
17 *
18 *
19 *
20 *
21 *
22 *
23 *
24 */
25
26 package java.security;
27
28 import java.util.*;
29 import java.lang.*;
30 import java.io.IOException;
31 import java.io.ByteArrayOutputStream;
32 import java.io.PrintStream;
33 import java.io.InputStream;
34 import java.io.ByteArrayInputStream;
35
36 import java.nio.ByteBuffer;
37
38 import sun.security.util.Debug;
39
40 /**
41 * This MessageDigest class provides applications the functionality of a
42 * message digest algorithm, such as SHA-1 or SHA-256.
43 * Message digests are secure one-way hash functions that take arbitrary-sized
44 * data and output a fixed-length hash value.
45 *
46 * <p>A MessageDigest object starts out initialized. The data is
47 * processed through it using the {@link #update(byte) update}
48 * methods. At any point {@link #reset() reset} can be called
49 * to reset the digest. Once all the data to be updated has been
50 * updated, one of the {@link #digest() digest} methods should
51 * be called to complete the hash computation.
52 *
53 * <p>The {@code digest} method can be called once for a given number
54 * of updates. After {@code digest} has been called, the MessageDigest
55 * object is reset to its initialized state.
56 *
57 * <p>Implementations are free to implement the Cloneable interface.
58 * Client applications can test cloneability by attempting cloning
59 * and catching the CloneNotSupportedException:
60 *
61 * <pre>{@code
62 * MessageDigest md = MessageDigest.getInstance("SHA");
63 *
64 * try {
65 * md.update(toChapter1);
66 * MessageDigest tc1 = md.clone();
67 * byte[] toChapter1Digest = tc1.digest();
68 * md.update(toChapter2);
69 * ...etc.
70 * } catch (CloneNotSupportedException cnse) {
71 * throw new DigestException("couldn't make digest of partial content");
72 * }
73 * }</pre>
74 *
75 * <p>Note that if a given implementation is not cloneable, it is
76 * still possible to compute intermediate digests by instantiating
77 * several instances, if the number of digests is known in advance.
78 *
79 * <p>Note that this class is abstract and extends from
80 * {@code MessageDigestSpi} for historical reasons.
81 * Application developers should only take notice of the methods defined in
82 * this {@code MessageDigest} class; all the methods in
83 * the superclass are intended for cryptographic service providers who wish to
84 * supply their own implementations of message digest algorithms.
85 *
86 * <p> Every implementation of the Java platform is required to support
87 * the following standard {@code MessageDigest} algorithms:
88 * <ul>
89 * <li>{@code MD5}</li>
90 * <li>{@code SHA-1}</li>
91 * <li>{@code SHA-256}</li>
92 * </ul>
93 * These algorithms are described in the <a href=
94 * "{@docRoot}/../technotes/guides/security/StandardNames.html#MessageDigest">
95 * MessageDigest section</a> of the
96 * Java Cryptography Architecture Standard Algorithm Name Documentation.
97 * Consult the release documentation for your implementation to see if any
98 * other algorithms are supported.
99 *
100 * @author Benjamin Renaud
101 *
102 * @see DigestInputStream
103 * @see DigestOutputStream
104 */
105
106 public abstract class MessageDigest extends MessageDigestSpi {
107
108 private static final Debug pdebug =
109 Debug.getInstance("provider", "Provider");
110 private static final boolean skipDebug =
111 Debug.isOn("engine=") && !Debug.isOn("messagedigest");
112
113 private String algorithm;
114
115 // The state of this digest
116 private static final int INITIAL = 0;
117 private static final int IN_PROGRESS = 1;
118 private int state = INITIAL;
119
120 // The provider
121 private Provider provider;
122
123 /**
124 * Creates a message digest with the specified algorithm name.
125 *
126 * @param algorithm the standard name of the digest algorithm.
127 * See the MessageDigest section in the <a href=
128 * "{@docRoot}/../technotes/guides/security/StandardNames.html#MessageDigest">
129 * Java Cryptography Architecture Standard Algorithm Name Documentation</a>
130 * for information about standard algorithm names.
131 */
132 protected MessageDigest(String algorithm) {
133 this.algorithm = algorithm;
134 }
135
136 /**
137 * Returns a MessageDigest object that implements the specified digest
138 * algorithm.
139 *
140 * <p> This method traverses the list of registered security Providers,
141 * starting with the most preferred Provider.
142 * A new MessageDigest object encapsulating the
143 * MessageDigestSpi implementation from the first
144 * Provider that supports the specified algorithm is returned.
145 *
146 * <p> Note that the list of registered providers may be retrieved via
147 * the {@link Security#getProviders() Security.getProviders()} method.
148 *
149 * @param algorithm the name of the algorithm requested.
150 * See the MessageDigest section in the <a href=
151 * "{@docRoot}/../technotes/guides/security/StandardNames.html#MessageDigest">
152 * Java Cryptography Architecture Standard Algorithm Name Documentation</a>
153 * for information about standard algorithm names.
154 *
155 * @return a Message Digest object that implements the specified algorithm.
156 *
157 * @exception NoSuchAlgorithmException if no Provider supports a
158 * MessageDigestSpi implementation for the
159 * specified algorithm.
160 *
161 * @see Provider
162 */
163 public static MessageDigest getInstance(String algorithm)
164 throws NoSuchAlgorithmException {
165 try {
166 MessageDigest md;
167 Object[] objs = Security.getImpl(algorithm, "MessageDigest",
168 (String)null);
169 if (objs[0] instanceof MessageDigest) {
170 md = (MessageDigest)objs[0];
171 } else {
172 md = new Delegate((MessageDigestSpi)objs[0], algorithm);
173 }
174 md.provider = (Provider)objs[1];
175
176 if (!skipDebug && pdebug != null) {
177 pdebug.println("MessageDigest." + algorithm +
178 " algorithm from: " + md.provider.getName());
179 }
180
181 return md;
182
183 } catch(NoSuchProviderException e) {
184 throw new NoSuchAlgorithmException(algorithm + " not found");
185 }
186 }
187
188 /**
189 * Returns a MessageDigest object that implements the specified digest
190 * algorithm.
191 *
192 * <p> A new MessageDigest object encapsulating the
193 * MessageDigestSpi implementation from the specified provider
194 * is returned. The specified provider must be registered
195 * in the security provider list.
196 *
197 * <p> Note that the list of registered providers may be retrieved via
198 * the {@link Security#getProviders() Security.getProviders()} method.
199 *
200 * @param algorithm the name of the algorithm requested.
201 * See the MessageDigest section in the <a href=
202 * "{@docRoot}/../technotes/guides/security/StandardNames.html#MessageDigest">
203 * Java Cryptography Architecture Standard Algorithm Name Documentation</a>
204 * for information about standard algorithm names.
205 *
206 * @param provider the name of the provider.
207 *
208 * @return a MessageDigest object that implements the specified algorithm.
209 *
210 * @exception NoSuchAlgorithmException if a MessageDigestSpi
211 * implementation for the specified algorithm is not
212 * available from the specified provider.
213 *
214 * @exception NoSuchProviderException if the specified provider is not
215 * registered in the security provider list.
216 *
217 * @exception IllegalArgumentException if the provider name is null
218 * or empty.
219 *
220 * @see Provider
221 */
222 public static MessageDigest getInstance(String algorithm, String provider)
223 throws NoSuchAlgorithmException, NoSuchProviderException
224 {
225 if (provider == null || provider.length() == 0)
226 throw new IllegalArgumentException("missing provider");
227 Object[] objs = Security.getImpl(algorithm, "MessageDigest", provider);
228 if (objs[0] instanceof MessageDigest) {
229 MessageDigest md = (MessageDigest)objs[0];
230 md.provider = (Provider)objs[1];
231 return md;
232 } else {
233 MessageDigest delegate =
234 new Delegate((MessageDigestSpi)objs[0], algorithm);
235 delegate.provider = (Provider)objs[1];
236 return delegate;
237 }
238 }
239
240 /**
241 * Returns a MessageDigest object that implements the specified digest
242 * algorithm.
243 *
244 * <p> A new MessageDigest object encapsulating the
245 * MessageDigestSpi implementation from the specified Provider
246 * object is returned. Note that the specified Provider object
247 * does not have to be registered in the provider list.
248 *
249 * @param algorithm the name of the algorithm requested.
250 * See the MessageDigest section in the <a href=
251 * "{@docRoot}/../technotes/guides/security/StandardNames.html#MessageDigest">
252 * Java Cryptography Architecture Standard Algorithm Name Documentation</a>
253 * for information about standard algorithm names.
254 *
255 * @param provider the provider.
256 *
257 * @return a MessageDigest object that implements the specified algorithm.
258 *
259 * @exception NoSuchAlgorithmException if a MessageDigestSpi
260 * implementation for the specified algorithm is not available
261 * from the specified Provider object.
262 *
263 * @exception IllegalArgumentException if the specified provider is null.
264 *
265 * @see Provider
266 *
267 * @since 1.4
268 */
269 public static MessageDigest getInstance(String algorithm,
270 Provider provider)
271 throws NoSuchAlgorithmException
272 {
273 if (provider == null)
274 throw new IllegalArgumentException("missing provider");
275 Object[] objs = Security.getImpl(algorithm, "MessageDigest", provider);
276 if (objs[0] instanceof MessageDigest) {
277 MessageDigest md = (MessageDigest)objs[0];
278 md.provider = (Provider)objs[1];
279 return md;
280 } else {
281 MessageDigest delegate =
282 new Delegate((MessageDigestSpi)objs[0], algorithm);
283 delegate.provider = (Provider)objs[1];
284 return delegate;
285 }
286 }
287
288 /**
289 * Returns the provider of this message digest object.
290 *
291 * @return the provider of this message digest object
292 */
293 public final Provider getProvider() {
294 return this.provider;
295 }
296
297 /**
298 * Updates the digest using the specified byte.
299 *
300 * @param input the byte with which to update the digest.
301 */
302 public void update(byte input) {
303 engineUpdate(input);
304 state = IN_PROGRESS;
305 }
306
307 /**
308 * Updates the digest using the specified array of bytes, starting
309 * at the specified offset.
310 *
311 * @param input the array of bytes.
312 *
313 * @param offset the offset to start from in the array of bytes.
314 *
315 * @param len the number of bytes to use, starting at
316 * {@code offset}.
317 */
318 public void update(byte[] input, int offset, int len) {
319 if (input == null) {
320 throw new IllegalArgumentException("No input buffer given");
321 }
322 if (input.length - offset < len) {
323 throw new IllegalArgumentException("Input buffer too short");
324 }
325 engineUpdate(input, offset, len);
326 state = IN_PROGRESS;
327 }
328
329 /**
330 * Updates the digest using the specified array of bytes.
331 *
332 * @param input the array of bytes.
333 */
334 public void update(byte[] input) {
335 engineUpdate(input, 0, input.length);
336 state = IN_PROGRESS;
337 }
338
339 /**
340 * Update the digest using the specified ByteBuffer. The digest is
341 * updated using the {@code input.remaining()} bytes starting
342 * at {@code input.position()}.
343 * Upon return, the buffer's position will be equal to its limit;
344 * its limit will not have changed.
345 *
346 * @param input the ByteBuffer
347 * @since 1.5
348 */
349 public final void update(ByteBuffer input) {
350 if (input == null) {
351 throw new NullPointerException();
352 }
353 engineUpdate(input);
354 state = IN_PROGRESS;
355 }
356
357 /**
358 * Completes the hash computation by performing final operations
359 * such as padding. The digest is reset after this call is made.
360 *
361 * @return the array of bytes for the resulting hash value.
362 */
363 public byte[] digest() {
364 /* Resetting is the responsibility of implementors. */
365 byte[] result = engineDigest();
366 state = INITIAL;
367 return result;
368 }
369
370 /**
371 * Completes the hash computation by performing final operations
372 * such as padding. The digest is reset after this call is made.
373 *
374 * @param buf output buffer for the computed digest
375 *
376 * @param offset offset into the output buffer to begin storing the digest
377 *
378 * @param len number of bytes within buf allotted for the digest
379 *
380 * @return the number of bytes placed into {@code buf}
381 *
382 * @exception DigestException if an error occurs.
383 */
384 public int digest(byte[] buf, int offset, int len) throws DigestException {
385 if (buf == null) {
386 throw new IllegalArgumentException("No output buffer given");
387 }
388 if (buf.length - offset < len) {
389 throw new IllegalArgumentException
390 ("Output buffer too small for specified offset and length");
391 }
392 int numBytes = engineDigest(buf, offset, len);
393 state = INITIAL;
394 return numBytes;
395 }
396
397 /**
398 * Performs a final update on the digest using the specified array
399 * of bytes, then completes the digest computation. That is, this
400 * method first calls {@link #update(byte[]) update(input)},
401 * passing the <i>input</i> array to the {@code update} method,
402 * then calls {@link #digest() digest()}.
403 *
404 * @param input the input to be updated before the digest is
405 * completed.
406 *
407 * @return the array of bytes for the resulting hash value.
408 */
409 public byte[] digest(byte[] input) {
410 update(input);
411 return digest();
412 }
413
414 /**
415 * Returns a string representation of this message digest object.
416 */
417 public String toString() {
418 ByteArrayOutputStream baos = new ByteArrayOutputStream();
419 PrintStream p = new PrintStream(baos);
420 p.print(algorithm+" Message Digest from "+provider.getName()+", ");
421 switch (state) {
422 case INITIAL:
423 p.print("<initialized>");
424 break;
425 case IN_PROGRESS:
426 p.print("<in progress>");
427 break;
428 }
429 p.println();
430 return (baos.toString());
431 }
432
433 /**
434 * Compares two digests for equality. Does a simple byte compare.
435 *
436 * @param digesta one of the digests to compare.
437 *
438 * @param digestb the other digest to compare.
439 *
440 * @return true if the digests are equal, false otherwise.
441 */
442 public static boolean isEqual(byte[] digesta, byte[] digestb) {
443 if (digesta == digestb) return true;
444 if (digesta == null || digestb == null) {
445 return false;
446 }
447 if (digesta.length != digestb.length) {
448 return false;
449 }
450
451 int result = 0;
452 // time-constant comparison
453 for (int i = 0; i < digesta.length; i++) {
454 result |= digesta[i] ^ digestb[i];
455 }
456 return result == 0;
457 }
458
459 /**
460 * Resets the digest for further use.
461 */
462 public void reset() {
463 engineReset();
464 state = INITIAL;
465 }
466
467 /**
468 * Returns a string that identifies the algorithm, independent of
469 * implementation details. The name should be a standard
470 * Java Security name (such as "SHA", "MD5", and so on).
471 * See the MessageDigest section in the <a href=
472 * "{@docRoot}/../technotes/guides/security/StandardNames.html#MessageDigest">
473 * Java Cryptography Architecture Standard Algorithm Name Documentation</a>
474 * for information about standard algorithm names.
475 *
476 * @return the name of the algorithm
477 */
478 public final String getAlgorithm() {
479 return this.algorithm;
480 }
481
482 /**
483 * Returns the length of the digest in bytes, or 0 if this operation is
484 * not supported by the provider and the implementation is not cloneable.
485 *
486 * @return the digest length in bytes, or 0 if this operation is not
487 * supported by the provider and the implementation is not cloneable.
488 *
489 * @since 1.2
490 */
491 public final int getDigestLength() {
492 int digestLen = engineGetDigestLength();
493 if (digestLen == 0) {
494 try {
495 MessageDigest md = (MessageDigest)clone();
496 byte[] digest = md.digest();
497 return digest.length;
498 } catch (CloneNotSupportedException e) {
499 return digestLen;
500 }
501 }
502 return digestLen;
503 }
504
505 /**
506 * Returns a clone if the implementation is cloneable.
507 *
508 * @return a clone if the implementation is cloneable.
509 *
510 * @exception CloneNotSupportedException if this is called on an
511 * implementation that does not support {@code Cloneable}.
512 */
513 public Object clone() throws CloneNotSupportedException {
514 if (this instanceof Cloneable) {
515 return super.clone();
516 } else {
517 throw new CloneNotSupportedException();
518 }
519 }
520
521
522
523
524 /*
525 * The following class allows providers to extend from MessageDigestSpi
526 * rather than from MessageDigest. It represents a MessageDigest with an
527 * encapsulated, provider-supplied SPI object (of type MessageDigestSpi).
528 * If the provider implementation is an instance of MessageDigestSpi,
529 * the getInstance() methods above return an instance of this class, with
530 * the SPI object encapsulated.
531 *
532 * Note: All SPI methods from the original MessageDigest class have been
533 * moved up the hierarchy into a new class (MessageDigestSpi), which has
534 * been interposed in the hierarchy between the API (MessageDigest)
535 * and its original parent (Object).
536 */
537
538 static class Delegate extends MessageDigest {
539
540 // The provider implementation (delegate)
541 private MessageDigestSpi digestSpi;
542
543 // constructor
544 public Delegate(MessageDigestSpi digestSpi, String algorithm) {
545 super(algorithm);
546 this.digestSpi = digestSpi;
547 }
548
549 /**
550 * Returns a clone if the delegate is cloneable.
551 *
552 * @return a clone if the delegate is cloneable.
553 *
554 * @exception CloneNotSupportedException if this is called on a
555 * delegate that does not support {@code Cloneable}.
556 */
557 public Object clone() throws CloneNotSupportedException {
558 if (digestSpi instanceof Cloneable) {
559 MessageDigestSpi digestSpiClone =
560 (MessageDigestSpi)digestSpi.clone();
561 // Because 'algorithm', 'provider', and 'state' are private
562 // members of our supertype, we must perform a cast to
563 // access them.
564 MessageDigest that =
565 new Delegate(digestSpiClone,
566 ((MessageDigest)this).algorithm);
567 that.provider = ((MessageDigest)this).provider;
568 that.state = ((MessageDigest)this).state;
569 return that;
570 } else {
571 throw new CloneNotSupportedException();
572 }
573 }
574
575 protected int engineGetDigestLength() {
576 return digestSpi.engineGetDigestLength();
577 }
578
579 protected void engineUpdate(byte input) {
580 digestSpi.engineUpdate(input);
581 }
582
583 protected void engineUpdate(byte[] input, int offset, int len) {
584 digestSpi.engineUpdate(input, offset, len);
585 }
586
587 protected void engineUpdate(ByteBuffer input) {
588 digestSpi.engineUpdate(input);
589 }
590
591 protected byte[] engineDigest() {
592 return digestSpi.engineDigest();
593 }
594
595 protected int engineDigest(byte[] buf, int offset, int len)
596 throws DigestException {
597 return digestSpi.engineDigest(buf, offset, len);
598 }
599
600 protected void engineReset() {
601 digestSpi.engineReset();
602 }
603 }
604 }
605