Improve docs

java/ql/src/Security/CWE/CWE-328/WeakHashingProperty.java

@@ -0,0 +1,9 @@
+import java.io.FileInputStream;
+import java.util.Properties;
+import java.security.MessageDigest;
+
+Properties props = Properties.load(new FileInputStream("settings.properties"));
+
+// BAD: the `hashAlgorithm` variable in `settings.properties` is `MD5` which is
+// a weak hashing algorithm.
+MessageDigest.getInstance(props.getProperty("hashAlgorithm"));

java/ql/src/Security/CWE/CWE-328/WeakHashingProperty.qhelp

@@ -2,4 +2,31 @@
   "-//Semmle//qhelp//EN"
   "qhelp.dtd">
 <qhelp>
-<include src="../CWE-327/BrokenCryptoAlgorithm.qhelp" /></qhelp>
+  <overview>
+    <p>
+      Using a weak hashing algorithm can result in attackers being able to
+      determine the original input to a hash function or create a second input
+      which will produce the same hash.
+    </p>
+  </overview>
+
+  <recommendation>
+    <p>Ensure you are using a strong, modern hashing algorithm, such as SHA-256.</p>
+  </recommendation>
+
+  <example>
+    <p>In the following (BAD) example, the <code>MD5</code> hashing algorithm is used, specified in a <code>.properties</code> file.</p>
+
+    <sample src="settings.properties"/>
+
+    <sample src="WeakHashingProperty.java"/>
+
+  </example>
+
+  <references>
+    <li>NIST, FIPS 140 Annex a: <a href="http://csrc.nist.gov/publications/fips/fips140-2/fips1402annexa.pdf">
+Approved Security Functions</a>.</li>
+    <li>NIST, SP 800-131A: <a href="http://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-131Ar1.pdf">
+Transitions: Recommendation for Transitioning the Use of Cryptographic Algorithms and Key Lengths</a>.</li>
+  </references>
+</qhelp>

java/ql/src/Security/CWE/CWE-328/settings.properties

@@ -0,0 +1 @@
+hashAlgorithm=MD5