Java tutorial
/* * Copyright (c) 1996, 2017, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package java.security; import java.util.*; import java.io.ByteArrayOutputStream; import java.io.PrintStream; import java.nio.ByteBuffer; import sun.security.util.Debug; import sun.security.util.MessageDigestSpi2; import javax.crypto.SecretKey; /** * This MessageDigest class provides applications the functionality of a * message digest algorithm, such as SHA-1 or SHA-256. * Message digests are secure one-way hash functions that take arbitrary-sized * data and output a fixed-length hash value. * * <p>A MessageDigest object starts out initialized. The data is * processed through it using the {@link #update(byte) update} * methods. At any point {@link #reset() reset} can be called * to reset the digest. Once all the data to be updated has been * updated, one of the {@link #digest() digest} methods should * be called to complete the hash computation. * * <p>The {@code digest} method can be called once for a given number * of updates. After {@code digest} has been called, the MessageDigest * object is reset to its initialized state. * * <p>Implementations are free to implement the Cloneable interface. * Client applications can test cloneability by attempting cloning * and catching the CloneNotSupportedException: * * <pre>{@code * MessageDigest md = MessageDigest.getInstance("SHA-256"); * * try { * md.update(toChapter1); * MessageDigest tc1 = md.clone(); * byte[] toChapter1Digest = tc1.digest(); * md.update(toChapter2); * ...etc. * } catch (CloneNotSupportedException cnse) { * throw new DigestException("couldn't make digest of partial content"); * } * }</pre> * * <p>Note that if a given implementation is not cloneable, it is * still possible to compute intermediate digests by instantiating * several instances, if the number of digests is known in advance. * * <p>Note that this class is abstract and extends from * {@code MessageDigestSpi} for historical reasons. * Application developers should only take notice of the methods defined in * this {@code MessageDigest} class; all the methods in * the superclass are intended for cryptographic service providers who wish to * supply their own implementations of message digest algorithms. * * <p> Every implementation of the Java platform is required to support * the following standard {@code MessageDigest} algorithms: * <ul> * <li>{@code MD5}</li> * <li>{@code SHA-1}</li> * <li>{@code SHA-256}</li> * </ul> * These algorithms are described in the <a href= * "{@docRoot}/../specs/security/standard-names.html#messagedigest-algorithms"> * MessageDigest section</a> of the * Java Security Standard Algorithm Names Specification. * Consult the release documentation for your implementation to see if any * other algorithms are supported. * * @author Benjamin Renaud * @since 1.1 * * @see DigestInputStream * @see DigestOutputStream */ public abstract class MessageDigest extends MessageDigestSpi { private static final Debug pdebug = Debug.getInstance("provider", "Provider"); private static final boolean skipDebug = Debug.isOn("engine=") && !Debug.isOn("messagedigest"); private String algorithm; // The state of this digest private static final int INITIAL = 0; private static final int IN_PROGRESS = 1; private int state = INITIAL; // The provider private Provider provider; /** * Creates a message digest with the specified algorithm name. * * @param algorithm the standard name of the digest algorithm. * See the MessageDigest section in the <a href= * "{@docRoot}/../specs/security/standard-names.html#messagedigest-algorithms"> * Java Security Standard Algorithm Names Specification</a> * for information about standard algorithm names. */ protected MessageDigest(String algorithm) { this.algorithm = algorithm; } /** * Returns a MessageDigest object that implements the specified digest * algorithm. * * <p> This method traverses the list of registered security Providers, * starting with the most preferred Provider. * A new MessageDigest object encapsulating the * MessageDigestSpi implementation from the first * Provider that supports the specified algorithm is returned. * * <p> Note that the list of registered providers may be retrieved via * the {@link Security#getProviders() Security.getProviders()} method. * * @implNote * The JDK Reference Implementation additionally uses the * {@code jdk.security.provider.preferred} * {@link Security#getProperty(String) Security} property to determine * the preferred provider order for the specified algorithm. This * may be different than the order of providers returned by * {@link Security#getProviders() Security.getProviders()}. * * @param algorithm the name of the algorithm requested. * See the MessageDigest section in the <a href= * "{@docRoot}/../specs/security/standard-names.html#messagedigest-algorithms"> * Java Security Standard Algorithm Names Specification</a> * for information about standard algorithm names. * * @return a {@code MessageDigest} object that implements the * specified algorithm * * @throws NoSuchAlgorithmException if no {@code Provider} supports a * {@code MessageDigestSpi} implementation for the * specified algorithm * * @throws NullPointerException if {@code algorithm} is {@code null} * * @see Provider */ public static MessageDigest getInstance(String algorithm) throws NoSuchAlgorithmException { Objects.requireNonNull(algorithm, "null algorithm name"); try { MessageDigest md; Object[] objs = Security.getImpl(algorithm, "MessageDigest", (String) null); if (objs[0] instanceof MessageDigest) { md = (MessageDigest) objs[0]; } else { md = new Delegate((MessageDigestSpi) objs[0], algorithm); } md.provider = (Provider) objs[1]; if (!skipDebug && pdebug != null) { pdebug.println("MessageDigest." + algorithm + " algorithm from: " + md.provider.getName()); } return md; } catch (NoSuchProviderException e) { throw new NoSuchAlgorithmException(algorithm + " not found"); } } /** * Returns a MessageDigest object that implements the specified digest * algorithm. * * <p> A new MessageDigest object encapsulating the * MessageDigestSpi implementation from the specified provider * is returned. The specified provider must be registered * in the security provider list. * * <p> Note that the list of registered providers may be retrieved via * the {@link Security#getProviders() Security.getProviders()} method. * * @param algorithm the name of the algorithm requested. * See the MessageDigest section in the <a href= * "{@docRoot}/../specs/security/standard-names.html#messagedigest-algorithms"> * Java Security Standard Algorithm Names Specification</a> * for information about standard algorithm names. * * @param provider the name of the provider. * * @return a {@code MessageDigest} object that implements the * specified algorithm * * @throws IllegalArgumentException if the provider name is {@code null} * or empty * * @throws NoSuchAlgorithmException if a {@code MessageDigestSpi} * implementation for the specified algorithm is not * available from the specified provider * * @throws NoSuchProviderException if the specified provider is not * registered in the security provider list * * @throws NullPointerException if {@code algorithm} is {@code null} * * @see Provider */ public static MessageDigest getInstance(String algorithm, String provider) throws NoSuchAlgorithmException, NoSuchProviderException { Objects.requireNonNull(algorithm, "null algorithm name"); if (provider == null || provider.isEmpty()) throw new IllegalArgumentException("missing provider"); Object[] objs = Security.getImpl(algorithm, "MessageDigest", provider); if (objs[0] instanceof MessageDigest) { MessageDigest md = (MessageDigest) objs[0]; md.provider = (Provider) objs[1]; return md; } else { MessageDigest delegate = new Delegate((MessageDigestSpi) objs[0], algorithm); delegate.provider = (Provider) objs[1]; return delegate; } } /** * Returns a MessageDigest object that implements the specified digest * algorithm. * * <p> A new MessageDigest object encapsulating the * MessageDigestSpi implementation from the specified Provider * object is returned. Note that the specified Provider object * does not have to be registered in the provider list. * * @param algorithm the name of the algorithm requested. * See the MessageDigest section in the <a href= * "{@docRoot}/../specs/security/standard-names.html#messagedigest-algorithms"> * Java Security Standard Algorithm Names Specification</a> * for information about standard algorithm names. * * @param provider the provider. * * @return a {@code MessageDigest} object that implements the * specified algorithm * * @throws IllegalArgumentException if the specified provider is * {@code null} * * @throws NoSuchAlgorithmException if a {@code MessageDigestSpi} * implementation for the specified algorithm is not available * from the specified {@code Provider} object * * @throws NullPointerException if {@code algorithm} is {@code null} * * @see Provider * * @since 1.4 */ public static MessageDigest getInstance(String algorithm, Provider provider) throws NoSuchAlgorithmException { Objects.requireNonNull(algorithm, "null algorithm name"); if (provider == null) throw new IllegalArgumentException("missing provider"); Object[] objs = Security.getImpl(algorithm, "MessageDigest", provider); if (objs[0] instanceof MessageDigest) { MessageDigest md = (MessageDigest) objs[0]; md.provider = (Provider) objs[1]; return md; } else { MessageDigest delegate = new Delegate((MessageDigestSpi) objs[0], algorithm); delegate.provider = (Provider) objs[1]; return delegate; } } /** * Returns the provider of this message digest object. * * @return the provider of this message digest object */ public final Provider getProvider() { return this.provider; } /** * Updates the digest using the specified byte. * * @param input the byte with which to update the digest. */ public void update(byte input) { engineUpdate(input); state = IN_PROGRESS; } /** * Updates the digest using the specified array of bytes, starting * at the specified offset. * * @param input the array of bytes. * * @param offset the offset to start from in the array of bytes. * * @param len the number of bytes to use, starting at * {@code offset}. */ public void update(byte[] input, int offset, int len) { if (input == null) { throw new IllegalArgumentException("No input buffer given"); } if (input.length - offset < len) { throw new IllegalArgumentException("Input buffer too short"); } engineUpdate(input, offset, len); state = IN_PROGRESS; } /** * Updates the digest using the specified array of bytes. * * @param input the array of bytes. */ public void update(byte[] input) { engineUpdate(input, 0, input.length); state = IN_PROGRESS; } /** * Update the digest using the specified ByteBuffer. The digest is * updated using the {@code input.remaining()} bytes starting * at {@code input.position()}. * Upon return, the buffer's position will be equal to its limit; * its limit will not have changed. * * @param input the ByteBuffer * @since 1.5 */ public final void update(ByteBuffer input) { if (input == null) { throw new NullPointerException(); } engineUpdate(input); state = IN_PROGRESS; } /** * Completes the hash computation by performing final operations * such as padding. The digest is reset after this call is made. * * @return the array of bytes for the resulting hash value. */ public byte[] digest() { /* Resetting is the responsibility of implementors. */ byte[] result = engineDigest(); state = INITIAL; return result; } /** * Completes the hash computation by performing final operations * such as padding. The digest is reset after this call is made. * * @param buf output buffer for the computed digest * * @param offset offset into the output buffer to begin storing the digest * * @param len number of bytes within buf allotted for the digest * * @return the number of bytes placed into {@code buf} * * @exception DigestException if an error occurs. */ public int digest(byte[] buf, int offset, int len) throws DigestException { if (buf == null) { throw new IllegalArgumentException("No output buffer given"); } if (buf.length - offset < len) { throw new IllegalArgumentException("Output buffer too small for specified offset and length"); } int numBytes = engineDigest(buf, offset, len); state = INITIAL; return numBytes; } /** * Performs a final update on the digest using the specified array * of bytes, then completes the digest computation. That is, this * method first calls {@link #update(byte[]) update(input)}, * passing the <i>input</i> array to the {@code update} method, * then calls {@link #digest() digest()}. * * @param input the input to be updated before the digest is * completed. * * @return the array of bytes for the resulting hash value. */ public byte[] digest(byte[] input) { update(input); return digest(); } private String getProviderName() { return (provider == null) ? "(no provider)" : provider.getName(); } /** * Returns a string representation of this message digest object. */ public String toString() { ByteArrayOutputStream baos = new ByteArrayOutputStream(); PrintStream p = new PrintStream(baos); p.print(algorithm + " Message Digest from " + getProviderName() + ", "); switch (state) { case INITIAL: p.print("<initialized>"); break; case IN_PROGRESS: p.print("<in progress>"); break; } p.println(); return (baos.toString()); } /** * Compares two digests for equality. Two digests are equal if they have * the same length and all bytes at corresponding positions are equal. * * @implNote * If the digests are the same length, all bytes are examined to * determine equality. * * @param digesta one of the digests to compare. * * @param digestb the other digest to compare. * * @return true if the digests are equal, false otherwise. */ public static boolean isEqual(byte[] digesta, byte[] digestb) { if (digesta == digestb) return true; if (digesta == null || digestb == null) { return false; } if (digesta.length != digestb.length) { return false; } int result = 0; // time-constant comparison for (int i = 0; i < digesta.length; i++) { result |= digesta[i] ^ digestb[i]; } return result == 0; } /** * Resets the digest for further use. */ public void reset() { engineReset(); state = INITIAL; } /** * Returns a string that identifies the algorithm, independent of * implementation details. The name should be a standard * Java Security name (such as "SHA-256"). * See the MessageDigest section in the <a href= * "{@docRoot}/../specs/security/standard-names.html#messagedigest-algorithms"> * Java Security Standard Algorithm Names Specification</a> * for information about standard algorithm names. * * @return the name of the algorithm */ public final String getAlgorithm() { return this.algorithm; } /** * Returns the length of the digest in bytes, or 0 if this operation is * not supported by the provider and the implementation is not cloneable. * * @return the digest length in bytes, or 0 if this operation is not * supported by the provider and the implementation is not cloneable. * * @since 1.2 */ public final int getDigestLength() { int digestLen = engineGetDigestLength(); if (digestLen == 0) { try { MessageDigest md = (MessageDigest) clone(); byte[] digest = md.digest(); return digest.length; } catch (CloneNotSupportedException e) { return digestLen; } } return digestLen; } /** * Returns a clone if the implementation is cloneable. * * @return a clone if the implementation is cloneable. * * @exception CloneNotSupportedException if this is called on an * implementation that does not support {@code Cloneable}. */ public Object clone() throws CloneNotSupportedException { if (this instanceof Cloneable) { return super.clone(); } else { throw new CloneNotSupportedException(); } } /* * The following class allows providers to extend from MessageDigestSpi * rather than from MessageDigest. It represents a MessageDigest with an * encapsulated, provider-supplied SPI object (of type MessageDigestSpi). * If the provider implementation is an instance of MessageDigestSpi, * the getInstance() methods above return an instance of this class, with * the SPI object encapsulated. * * Note: All SPI methods from the original MessageDigest class have been * moved up the hierarchy into a new class (MessageDigestSpi), which has * been interposed in the hierarchy between the API (MessageDigest) * and its original parent (Object). */ static class Delegate extends MessageDigest implements MessageDigestSpi2 { // The provider implementation (delegate) private MessageDigestSpi digestSpi; // constructor public Delegate(MessageDigestSpi digestSpi, String algorithm) { super(algorithm); this.digestSpi = digestSpi; } /** * Returns a clone if the delegate is cloneable. * * @return a clone if the delegate is cloneable. * * @exception CloneNotSupportedException if this is called on a * delegate that does not support {@code Cloneable}. */ public Object clone() throws CloneNotSupportedException { if (digestSpi instanceof Cloneable) { MessageDigestSpi digestSpiClone = (MessageDigestSpi) digestSpi.clone(); // Because 'algorithm', 'provider', and 'state' are private // members of our supertype, we must perform a cast to // access them. MessageDigest that = new Delegate(digestSpiClone, ((MessageDigest) this).algorithm); that.provider = ((MessageDigest) this).provider; that.state = ((MessageDigest) this).state; return that; } else { throw new CloneNotSupportedException(); } } protected int engineGetDigestLength() { return digestSpi.engineGetDigestLength(); } protected void engineUpdate(byte input) { digestSpi.engineUpdate(input); } protected void engineUpdate(byte[] input, int offset, int len) { digestSpi.engineUpdate(input, offset, len); } protected void engineUpdate(ByteBuffer input) { digestSpi.engineUpdate(input); } public void engineUpdate(SecretKey key) throws InvalidKeyException { if (digestSpi instanceof MessageDigestSpi2) { ((MessageDigestSpi2) digestSpi).engineUpdate(key); } else { throw new UnsupportedOperationException("Digest does not support update of SecretKey object"); } } protected byte[] engineDigest() { return digestSpi.engineDigest(); } protected int engineDigest(byte[] buf, int offset, int len) throws DigestException { return digestSpi.engineDigest(buf, offset, len); } protected void engineReset() { digestSpi.engineReset(); } } }