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 }