Cherry-pick "Remove insecure MD5 from documentation"

Author: Xerkus

docs/book/adapter/dbtable/credential-treatment.md

@@ -3,8 +3,12 @@
 `Zend\Authentication\Adapter\DbTable\CredentialTreatmentAdapter` will execute a
 SQL query containing the provided identity and credentials, passing the
 credentials to a *credential treatment* function defined on the RDBMS server;
-if an identity is returned, authentication succeeds. Common credential
-treatments include `MD5()` and `PASSWORD()`.
+if an identity is returned, authentication succeeds. Credential
+treatments depends on your RDBMS, and while simple hashing function such as
+`md5` and `sha1` are generally available, it is recommended not to use them and
+rather use the RDBMS specific function such as
+[`PASSWORD(?)` for MySQL](http://dev.mysql.com/doc/refman/5.7/en/password-hashing.html).
+More details are available in the next section.
 
 ## Configuration Options
 
@@ -23,7 +27,7 @@ The available configuration options include:
 - `credentialTreatment`: In many cases, passwords and other sensitive data
   are encrypted, hashed, encoded, obscured, salted or otherwise treated through
   some function or algorithm. By specifying a parameterized treatment string
-  with this method, such as '`MD5(?)`' or '`PASSWORD(?)`', a developer may
+  with this method, such as '`PASSWORD(?)`', a developer may
   apply such arbitrary SQL upon input credential data. Since these functions
   are specific to the underlying RDBMS, check the database manual for the
   availability of such functions for your database system.
@@ -186,7 +190,7 @@ credential treatment to solve more complex problems.
 
 ### Check for compromised user
 
-In this scenario, we use the credential treatment `MD5()`, but also check to see
+In this scenario, we use the credential treatment `PASSWORD()`, but also check to see
 that the user has not been flagged as "compromised", which is a potential value
 of the `status` field for the user record.
 
@@ -199,7 +203,7 @@ $adapter = new AuthAdapter(
     'users',
     'username',
     'password',
-    'MD5(?) AND status != "compromised"'
+    'PASSWORD(?) AND status != "compromised"'
 );
 ```
 
@@ -218,7 +222,7 @@ $adapter = new AuthAdapter(
     'users',
     'username',
     'password',
-    'MD5(?) AND active = "TRUE"'
+    'PASSWORD(?) AND active = "TRUE"'
 );
 ```
 
@@ -238,7 +242,9 @@ $sqlAlter = "ALTER TABLE [users] "
     . "AFTER [password]";
 ```
 
-Salts should be created *for each user* using a cryptographically sound pseudo-random number generator (CSPRNG). PHP 7 provides an implementation via `random_bytes`:
+Salts should be created *for each user* using a cryptographically sound pseudo-random number generator (CSPRNG).
+PHP 7 provides an implementation via `random_bytes` (and 
+[`random_compat` for older supported versions of PHP](https://github.com/paragonie/random_compat)):
 
 ```php
 $salt = random_bytes(32);
@@ -267,7 +273,7 @@ $db,
     'users',
     'username',
     'password',
-    "MD5(CONCAT('staticSalt', ?, password_salt))"
+    "PASSWORD(CONCAT('staticSalt', ?, password_salt))"
 );
 ```
 
@@ -304,13 +310,13 @@ The following uses the second example in this section, adding another `WHERE`
 clause to determine if the user is active in the system.
 
 ```php
-// Create a basic adapter, with only an MD5() credential treatment:
+// Create a basic adapter, with only an PASSWORD() credential treatment:
 $adapter = new AuthAdapter(
     $db,
     'users',
     'username',
     'password',
-    'MD5(?)'
+    'PASSWORD(?)'
 );
 
 // Now retrieve the Select instance and modify it: