update documentation following docs review

Author: karimhamdanali

swift/ql/src/queries/Security/CWE-916/InsufficientHashIterations.qhelp

@@ -3,15 +3,16 @@
   "qhelp.dtd">
 <qhelp>
   <overview>
-    <p>Using hash functions with less than 1,000 iterations is not secure. That scheme is vulnerable to password cracking attacks due to having an insufficient level of computational effort.</p>
+    <p>Storing cryptographic hashes of passwords is standard security practice, but it is equally important to select the right hashing scheme. If an attacker obtains the hashed passwords of an application, the password hashing scheme should still prevent the attacker from easily obtaining the original cleartext passwords.</p>
+    <p>A good password hashing scheme requires a computation that cannot be done efficiently. Hashing schemes with low number of iterations are efficiently computable, and are therefore not suitable for password hashing.</p>
   </overview>
 
   <recommendation>
-    <p>Use sufficient number of iterations (that is, greater than or equal 120000) for generating password-based keys.</p>
+    <p>Use the OWASP recommendation for sufficient number of iterations (currently, that is greater than or equal to 120,000) for password hashing schemes.</p>
   </recommendation>
 
   <example>
-    <p>The following example shows a few cases of instantiating a password-based key. In the 'BAD' cases, the key is initialized with insufficient iterations, making it susceptible to password cracking attacks. In the 'GOOD' cases, the key is initialized with at least 120000 iterations, which protects the encrypted data against recovery.</p>
+    <p>The following example shows a few cases where a password hashing scheme is instantiated. In the 'BAD' cases, the scheme is initialized with insufficient iterations, making it susceptible to password cracking attacks. In the 'GOOD' cases, the scheme is initialized with at least 120,000 iterations, which protects the hashed data against recovery.</p>
     <sample src="InsufficientHashIterations.swift" />
   </example>
 

swift/ql/src/queries/Security/CWE-916/InsufficientHashIterations.swift

@@ -2,11 +2,11 @@
 func encrypt() {
 	// ...
 
-	// BAD: Using insufficient (i.e., < 120,000) hash iterations keys for encryption
+	// BAD: Using insufficient (that is, < 120,000) hash iterations keys for encryption
 	_ = try PKCS5.PBKDF1(password: getRandomArray(), salt: getRandomArray(), iterations: 90000, keyLength: 0)
 	_ = try PKCS5.PBKDF2(password: getRandomArray(), salt: getRandomArray(), iterations: 90000, keyLength: 0)
 
-	// GOOD: Using sufficient (i.e., >= 120,000) hash iterations keys for encryption
+	// GOOD: Using sufficient (that is, >= 120,000) hash iterations keys for encryption
 	_ = try PKCS5.PBKDF1(password: getRandomArray(), salt: getRandomArray(), iterations: 120120, keyLength: 0)
 	_ = try PKCS5.PBKDF2(password: getRandomArray(), salt: getRandomArray(), iterations: 120120, keyLength: 0)