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 26package java.security; 27 28import java.util.*; 29import java.io.ByteArrayOutputStream; 30import java.io.PrintStream; 31import java.nio.ByteBuffer; 32 33import sun.security.util.Debug; 34import sun.security.util.MessageDigestSpi2; 35 36import 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"); 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 105public 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.length() == 0) 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", "MD5", and so on). 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