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