ANY23-553 Document MathUtils#md5 to warn that the weak hash algorithm…

… is not to be used in a sensitive context (#242)

core/src/main/java/org/apache/any23/rdf/RDFUtils.java

@@ -373,7 +373,7 @@ public static BNode bnode() {
     }
 
     /**
-     * Creates a {@link BNode}.
+     * Creates a {@link BNode} with an MD5 digest as part of the ID.
      * 
      * @param id
      *            string representation of the {@link org.eclipse.rdf4j.model.BNode} name for which we will create a md5

core/src/main/java/org/apache/any23/util/MathUtils.java

@@ -22,7 +22,7 @@
 import java.security.NoSuchAlgorithmException;
 
 /**
- * General utility functions.
+ * Mathematical utility functions.
  *
  * @author Michele Mostarda (mostarda@fbk.eu)
  * @author Davide Palmisano (palmisano@fbk.eu)
@@ -32,6 +32,23 @@ public class MathUtils {
     private MathUtils() {
     }
 
+    /**
+     * <p>
+     * Create a MD5 <b>weak hash</b> for a given string.
+     * </p>
+     * <p>
+     * <b>N.B. This method MUST never be used in a sensitive context</b>. Examples of such usage include (i)
+     * User-password storage, (ii) Security token generation (used to confirm e-mail when registering on a website,
+     * reset password, etc...), (iii) To compute some message integrity.
+     * </p>
+     * Current usage is limited to {@link org.apache.any23.rdf.RDFUtils#getBNode(String)} which is fine for the creation
+     * of blank node(s).
+     *
+     * @param s
+     *            input string to create an MD5 hash for.
+     *
+     * @return a string representation of a MD5 {@link java.security.MessageDigest}
+     */
     public static final String md5(String s) {
         try {
             MessageDigest md5 = MessageDigest.getInstance("MD5");

core/src/test/java/org/apache/any23/util/MathUtilsTest.java

@@ -0,0 +1,46 @@
+/*
+ * 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.any23.util;
+
+import static org.junit.Assert.assertEquals;
+
+import org.junit.Test;
+
+/**
+ * Unit tests for {@link org.apache.any23.util.MathUtils}
+ *
+ */
+public class MathUtilsTest {
+
+    /**
+     * Test method for {@link org.apache.any23.util.MathUtils#md5(java.lang.String)}.
+     */
+    @Test
+    public void testMd5() {
+        String testString1 = "https://any23.apache.org";
+        String expectedMd5String1 = "86f7ce8a90e269890b66ba13e6cdcf";
+        assertEquals(expectedMd5String1, MathUtils.md5(testString1));
+        String testString2 = "Apache Any23 is written in Java and licensed under the Apache "
+                + "License v2.0. Apache Any23 can be used in various ways: As a library "
+                + "in Java applications that consume structured data from the Web. As "
+                + "a command-line tool for extracting and converting between the supported "
+                + "formats. As online service API available at any23.org. ";
+        String expectedMd5String2 = "d621f85f79fff905c17bd59e3cc61e1";
+        assertEquals(expectedMd5String2, MathUtils.md5(testString2));
+    }
+
+}

pom.xml

@@ -762,7 +762,7 @@
                 <rules>
                   <bannedDependencies>
                     <excludes>
-                      <exclude>org.apache.logging.log4j:log4j-core:(,2.16.0)</exclude>
+                      <exclude>org.apache.logging.log4j:log4j-core:(,2.17.1)</exclude>
                     </excludes>
                   </bannedDependencies>
                 </rules>