Add MessageDigestInputStream and deprecate

garydgregory · garydgregory · commit 50e2d770f98c · 2023-10-18T08:27:46.000-04:00
MessageDigestCalculatingInputStream
diff --git a/pom.xml b/pom.xml
@@ -288,6 +288,12 @@ file comparators, endian transformation classes, and much more.
       <version>3.13.0</version>
       <scope>test</scope>
     </dependency>
+    <dependency>
+      <groupId>commons-codec</groupId>
+      <artifactId>commons-codec</artifactId>
+      <version>1.16.0</version>
+      <scope>test</scope>
+    </dependency>
     <dependency>
       <groupId>org.openjdk.jmh</groupId>
       <artifactId>jmh-core</artifactId>
diff --git a/src/changes/changes.xml b/src/changes/changes.xml
@@ -121,6 +121,9 @@ The <action> type attribute can be add,update,fix,remove.
       <action dev="ggregory" type="add" due-to="Gary Gregory">
         Add org.apache.commons.io.StreamIterator.
       </action>
+      <action dev="ggregory" type="add" due-to="Gary Gregory">
+        Add MessageDigestInputStream and deprecate MessageDigestCalculatingInputStream.
+      </action>
       <!-- UPDATE -->
       <action dev="ggregory" type="update" due-to="Gary Gregory">
         Bump org.apache.commons:commons-parent from 62 to 64.
diff --git a/src/main/java/org/apache/commons/io/input/MessageDigestCalculatingInputStream.java b/src/main/java/org/apache/commons/io/input/MessageDigestCalculatingInputStream.java
@@ -27,7 +27,7 @@
 
 /**
  * This class is an example for using an {@link ObservableInputStream}. It creates its own {@link org.apache.commons.io.input.ObservableInputStream.Observer},
- * which calculates a checksum using a MessageDigest, for example an MD5 sum.
+ * which calculates a checksum using a {@link MessageDigest}, for example, a SHA-512 sum.
  * <p>
  * To build an instance, see {@link Builder}.
  * </p>
@@ -36,12 +36,11 @@
  * Cryptography Architecture Standard Algorithm Name Documentation</a> for information about standard algorithm names.
  * </p>
  * <p>
- * <em>Note</em>: Neither {@link ObservableInputStream}, nor {@link MessageDigest}, are thread safe. So is {@link MessageDigestCalculatingInputStream}.
- * </p>
- * <p>
- * TODO Rename to MessageDigestInputStream in 3.0.
+ * <em>Note</em>: Neither {@link ObservableInputStream}, nor {@link MessageDigest}, are thread safe, so is {@link MessageDigestCalculatingInputStream}.
  * </p>
+ * @deprecated Use {@link MessageDigestInputStream}.
  */
+@Deprecated
 public class MessageDigestCalculatingInputStream extends ObservableInputStream {
 
     /**
@@ -96,6 +95,9 @@ public MessageDigestCalculatingInputStream get() throws IOException {
 
         /**
          * Sets the message digest.
+         * <p>
+         * The MD5 cryptographic algorithm is weak and should not be used.
+         * </p>
          *
          * @param messageDigest the message digest.
          */
@@ -105,6 +107,9 @@ public void setMessageDigest(final MessageDigest messageDigest) {
 
         /**
          * Sets the name of the name of the message digest algorithm.
+         * <p>
+         * The MD5 cryptographic algorithm is weak and should not be used.
+         * </p>
          *
          * @param algorithm the name of the algorithm. See the MessageDigest section in the
          *                  <a href= "https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#MessageDigest"> Java Cryptography
@@ -192,6 +197,9 @@ public MessageDigestCalculatingInputStream(final InputStream inputStream) throws
 
     /**
      * Constructs a new instance, which calculates a signature on the given stream, using the given {@link MessageDigest}.
+     * <p>
+     * The MD5 cryptographic algorithm is weak and should not be used.
+     * </p>
      *
      * @param inputStream   the stream to calculate the message digest for
      * @param messageDigest the message digest to use
@@ -206,6 +214,9 @@ public MessageDigestCalculatingInputStream(final InputStream inputStream, final
 
     /**
      * Constructs a new instance, which calculates a signature on the given stream, using a {@link MessageDigest} with the given algorithm.
+     * <p>
+     * The MD5 cryptographic algorithm is weak and should not be used.
+     * </p>
      *
      * @param inputStream the stream to calculate the message digest for
      * @param algorithm   the name of the algorithm requested. See the MessageDigest section in the
diff --git a/src/main/java/org/apache/commons/io/input/MessageDigestInputStream.java b/src/main/java/org/apache/commons/io/input/MessageDigestInputStream.java
@@ -0,0 +1,193 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.commons.io.input;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.security.MessageDigest;
+import java.security.NoSuchAlgorithmException;
+import java.util.Objects;
+
+import org.apache.commons.io.build.AbstractStreamBuilder;
+
+/**
+ * This class is an example for using an {@link ObservableInputStream}. It creates its own {@link org.apache.commons.io.input.ObservableInputStream.Observer},
+ * which calculates a checksum using a {@link MessageDigest}, for example, a SHA-512 sum.
+ * <p>
+ * To build an instance, see {@link Builder}.
+ * </p>
+ * <p>
+ * See the MessageDigest section in the <a href= "https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#MessageDigest"> Java
+ * Cryptography Architecture Standard Algorithm Name Documentation</a> for information about standard algorithm names.
+ * </p>
+ * <p>
+ * You must specify a message digest algorithm name or instance.
+ * </p>
+ * <p>
+ * <em>Note</em>: Neither {@link ObservableInputStream}, nor {@link MessageDigest}, are thread safe, so is {@link MessageDigestInputStream}.
+ * </p>
+ *
+ * @since 2.15.0
+ */
+public final class MessageDigestInputStream extends ObservableInputStream {
+
+    /**
+     * Builds new {@link MessageDigestInputStream} instances.
+     * <p>
+     * For example:
+     * </p>
+     * <pre>{@code
+     * MessageDigestInputStream s = MessageDigestInputStream.builder()
+     *   .setPath(path)
+     *   .setMessageDigest("SHA-512")
+     *   .get();}
+     * </pre>
+     * <p>
+     * You must specify a message digest algorithm name or instance.
+     * </p>
+     */
+    public static class Builder extends AbstractStreamBuilder<MessageDigestInputStream, Builder> {
+
+        private MessageDigest messageDigest;
+
+        /**
+         * Constructs a new Builder.
+         */
+        public Builder() {
+            // empty
+        }
+
+        /**
+         * Constructs a new instance.
+         * <p>
+         * This builder use the aspects InputStream, OpenOption[], and MessageDigest.
+         * </p>
+         * <p>
+         * You must provide an origin that can be converted to an InputStream by this builder, otherwise, this call will throw an
+         * {@link UnsupportedOperationException}.
+         * </p>
+         *
+         * @return a new instance.
+         * @throws UnsupportedOperationException if the origin cannot provide an InputStream.
+         * @see #getInputStream()
+         */
+        @SuppressWarnings("resource")
+        @Override
+        public MessageDigestInputStream get() throws IOException {
+            return new MessageDigestInputStream(getInputStream(), messageDigest);
+        }
+
+        /**
+         * Sets the message digest.
+         * <p>
+         * The MD5 cryptographic algorithm is weak and should not be used.
+         * </p>
+         *
+         * @param messageDigest the message digest.
+         * @return this
+         */
+        public Builder setMessageDigest(final MessageDigest messageDigest) {
+            this.messageDigest = messageDigest;
+            return this;
+        }
+
+        /**
+         * Sets the name of the name of the message digest algorithm.
+         * <p>
+         * The MD5 cryptographic algorithm is weak and should not be used.
+         * </p>
+         *
+         * @param algorithm the name of the algorithm. See the MessageDigest section in the
+         *                  <a href= "https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#MessageDigest"> Java Cryptography
+         *                  Architecture Standard Algorithm Name Documentation</a> for information about standard algorithm names.
+         * @return this
+         * @throws NoSuchAlgorithmException if no Provider supports a MessageDigestSpi implementation for the specified algorithm.
+         */
+        public Builder setMessageDigest(final String algorithm) throws NoSuchAlgorithmException {
+            this.messageDigest = MessageDigest.getInstance(algorithm);
+            return this;
+        }
+
+    }
+
+    /**
+     * Maintains the message digest.
+     */
+    public static class MessageDigestMaintainingObserver extends Observer {
+
+        private final MessageDigest messageDigest;
+
+        /**
+         * Constructs an MessageDigestMaintainingObserver for the given MessageDigest.
+         *
+         * @param messageDigest the message digest to use
+         * @throws NullPointerException if messageDigest is null.
+         */
+        public MessageDigestMaintainingObserver(final MessageDigest messageDigest) {
+            this.messageDigest = Objects.requireNonNull(messageDigest, "messageDigest");
+        }
+
+        @Override
+        public void data(final byte[] input, final int offset, final int length) throws IOException {
+            messageDigest.update(input, offset, length);
+        }
+
+        @Override
+        public void data(final int input) throws IOException {
+            messageDigest.update((byte) input);
+        }
+    }
+
+    /**
+     * Constructs a new {@link Builder}.
+     *
+     * @return a new {@link Builder}.
+     */
+    public static Builder builder() {
+        return new Builder();
+    }
+
+    private final MessageDigest messageDigest;
+
+    /**
+     * Constructs a new instance, which calculates a signature on the given stream, using the given {@link MessageDigest}.
+     * <p>
+     * The MD5 cryptographic algorithm is weak and should not be used.
+     * </p>
+     *
+     * @param inputStream   the stream to calculate the message digest for
+     * @param messageDigest the message digest to use
+     * @throws NullPointerException if messageDigest is null.
+     */
+    private MessageDigestInputStream(final InputStream inputStream, final MessageDigest messageDigest) {
+        super(inputStream, new MessageDigestMaintainingObserver(messageDigest));
+        this.messageDigest = messageDigest;
+    }
+
+    /**
+     * Gets the {@link MessageDigest}, which is being used for generating the checksum.
+     * <p>
+     * <em>Note</em>: The checksum will only reflect the data, which has been read so far. This is probably not, what you expect. Make sure, that the complete
+     * data has been read, if that is what you want. The easiest way to do so is by invoking {@link #consume()}.
+     * </p>
+     *
+     * @return the message digest used
+     */
+    public MessageDigest getMessageDigest() {
+        return messageDigest;
+    }
+}
diff --git a/src/main/java/org/apache/commons/io/input/ObservableInputStream.java b/src/main/java/org/apache/commons/io/input/ObservableInputStream.java
@@ -39,7 +39,7 @@
  * be used.
  * </p>
  *
- * @see MessageDigestCalculatingInputStream
+ * @see MessageDigestInputStream
  */
 public class ObservableInputStream extends ProxyInputStream {
 
diff --git a/src/test/java/org/apache/commons/io/input/MessageDigestCalculatingInputStreamTest.java b/src/test/java/org/apache/commons/io/input/MessageDigestCalculatingInputStreamTest.java
@@ -20,40 +20,57 @@
 
 import java.io.ByteArrayInputStream;
 import java.security.MessageDigest;
-import java.util.Random;
 
+import org.apache.commons.codec.digest.DigestUtils;
+import org.apache.commons.codec.digest.MessageDigestAlgorithms;
+import org.apache.commons.io.input.MessageDigestCalculatingInputStream.Builder;
 import org.junit.jupiter.api.Test;
 
 /**
  * Tests {@link MessageDigestCalculatingInputStream}.
  */
+@SuppressWarnings("deprecation")
 public class MessageDigestCalculatingInputStreamTest {
 
-    public static byte[] generateRandomByteStream(final int pSize) {
-        final byte[] buffer = new byte[pSize];
-        final Random rnd = new Random();
-        rnd.nextBytes(buffer);
-        return buffer;
-    }
-
     @Test
-    public void test() throws Exception {
+    public void testNormalUse() throws Exception {
         for (int i = 256; i < 8192; i = i * 2) {
-            final byte[] buffer = generateRandomByteStream(i);
-            final MessageDigest messageDigest = MessageDigestCalculatingInputStream.getDefaultMessageDigest();
-            final byte[] expect = messageDigest.digest(buffer);
+            final byte[] buffer = MessageDigestInputStreamTest.generateRandomByteStream(i);
+            final MessageDigest defaultMessageDigest = MessageDigestCalculatingInputStream.getDefaultMessageDigest();
+            final byte[] defaultExpect = defaultMessageDigest.digest(buffer);
+            // Defaults
             try (MessageDigestCalculatingInputStream messageDigestInputStream = new MessageDigestCalculatingInputStream(new ByteArrayInputStream(buffer))) {
                 messageDigestInputStream.consume();
-                assertArrayEquals(expect, messageDigestInputStream.getMessageDigest().digest());
+                assertArrayEquals(defaultExpect, messageDigestInputStream.getMessageDigest().digest());
             }
             try (MessageDigestCalculatingInputStream messageDigestInputStream = MessageDigestCalculatingInputStream.builder()
                     .setInputStream(new ByteArrayInputStream(buffer)).get()) {
                 messageDigestInputStream.consume();
-                assertArrayEquals(expect, messageDigestInputStream.getMessageDigest().digest());
+                assertArrayEquals(defaultExpect, messageDigestInputStream.getMessageDigest().digest());
             }
             try (MessageDigestCalculatingInputStream messageDigestInputStream = MessageDigestCalculatingInputStream.builder().setByteArray(buffer).get()) {
                 messageDigestInputStream.consume();
-                assertArrayEquals(expect, messageDigestInputStream.getMessageDigest().digest());
+                assertArrayEquals(defaultExpect, messageDigestInputStream.getMessageDigest().digest());
+            }
+            // SHA-512
+            final byte[] sha512Expect = DigestUtils.sha512(buffer);
+            {
+                final Builder builder = MessageDigestCalculatingInputStream.builder();
+                builder.setMessageDigest(MessageDigestAlgorithms.SHA_512);
+                builder.setInputStream(new ByteArrayInputStream(buffer));
+                try (MessageDigestCalculatingInputStream messageDigestInputStream = builder.get()) {
+                    messageDigestInputStream.consume();
+                    assertArrayEquals(sha512Expect, messageDigestInputStream.getMessageDigest().digest());
+                }
+            }
+            {
+                final Builder builder = MessageDigestCalculatingInputStream.builder();
+                builder.setMessageDigest(MessageDigestAlgorithms.SHA_512);
+                builder.setInputStream(new ByteArrayInputStream(buffer));
+                try (MessageDigestCalculatingInputStream messageDigestInputStream = builder.get()) {
+                    messageDigestInputStream.consume();
+                    assertArrayEquals(sha512Expect, messageDigestInputStream.getMessageDigest().digest());
+                }
             }
         }
     }
diff --git a/src/test/java/org/apache/commons/io/input/MessageDigestInputStreamTest.java b/src/test/java/org/apache/commons/io/input/MessageDigestInputStreamTest.java
diff --git a/src/test/java/org/apache/commons/io/input/ObservableInputStreamTest.java b/src/test/java/org/apache/commons/io/input/ObservableInputStreamTest.java
diff --git a/src/test/java/org/apache/commons/io/input/TimestampedObserverTest.java b/src/test/java/org/apache/commons/io/input/TimestampedObserverTest.java

Original file line number	Diff line number	Diff line change
`@@ -39,7 +39,7 @@`
`39`	`39`	`* be used.`
`40`	`40`	`* </p>`
`41`	`41`	`*`
`42`		`- * @see MessageDigestCalculatingInputStream`
	`42`	`+ * @see MessageDigestInputStream`
`43`	`43`	`*/`
`44`	`44`	`public class ObservableInputStream extends ProxyInputStream {`
`45`	`45`