[#3356] Clarifying when you need a salt

Also filling in other details related to using BCrypt

Author: weaverryan

book/security.rst

@@ -1349,19 +1349,7 @@ You can now calculate the hashed password either programmatically
 (e.g. ``password_hash('ryanpass', PASSWORD_BCRYPT, array('cost' => 12));``)
 or via some online tool.
 
-.. caution::
-
-    If you're using PHP 5.4 or lower, you'll need to install the ``ircmaxell/password-compat``
-    library via Composer:
-
-    .. code-block:: json
-
-        {
-            "require": {
-                "...": "all the other dependencies...",
-                "ircmaxell/password-compat": "~1.0.3"
-            }
-        }
+.. include:: /cookbook/security/_ircmaxwell_password-compat.rst.inc
 
 Supported algorithms for this method depend on your PHP version. A full list
 is available by calling the PHP function :phpfunction:`hash_algos`.

cookbook/security/_ircmaxwell_password-compat.rst.inc

@@ -0,0 +1,13 @@
+.. caution::
+
+    If you're using PHP 5.4 or lower, you'll need to install the ``ircmaxell/password-compat``
+    library via Composer in order to be able to use the ``bcrypt`` encoder:
+
+    .. code-block:: json
+
+        {
+            "require": {
+                "...": "all the other dependencies...",
+                "ircmaxell/password-compat": "~1.0.3"
+            }
+        }

cookbook/security/entity_provider.rst

@@ -95,6 +95,8 @@ focus on the most important methods that come from the
         public function __construct()
         {
             $this->isActive = true;
+            // may not be needed, see section on salt below
+            // $this->salt = md5(uniqid(null, true));
         }
 
         /**
@@ -110,6 +112,8 @@ focus on the most important methods that come from the
          */
         public function getSalt()
         {
+            // you *may* need a real salt depending on your encoder
+            // see section on salt below
             return null;
         }
 
@@ -144,8 +148,9 @@ focus on the most important methods that come from the
             return serialize(array(
                 $this->id,
                 $this->username,
-                $this->salt,
                 $this->password,
+                // see section on salt below
+                // $this->salt,
             ));
         }
 
@@ -157,19 +162,13 @@ focus on the most important methods that come from the
             list (
                 $this->id,
                 $this->username,
-                $this->salt,
                 $this->password,
+                // see section on salt below
+                // $this->salt
             ) = unserialize($serialized);
         }
     }
 
-.. note::
-
-    If you choose to implement
-    :class:`Symfony\\Component\\Security\\Core\\User\\EquatableInterface`,
-    you determine yourself which properties need to be compared to distinguish
-    your user objects.
-
 .. tip::
 
     :ref:`Generate the database table <book-doctrine-creating-the-database-tables-schema>`
@@ -186,7 +185,7 @@ interface forces the class to implement the five following methods:
 
 * ``getRoles()``,
 * ``getPassword()``,
-* ``getPassword()``,
+* ``getSalt()``,
 * ``getUsername()``,
 * ``eraseCredentials()``
 
@@ -213,6 +212,20 @@ The next part will focus on how to authenticate one of these users
 thanks to the Doctrine entity user provider and a couple of lines of
 configuration.
 
+.. sidebar:: Do you need to use a Salt?
+
+    Yes. Hashing a password with a salt is a necessary step so that encoded
+    passwords can't be decoded. However, some encoders - like Bcrypt - have
+    a built-in salt mechanism. If you configure ``bcrypt`` as your encoder
+    in ``security.yml`` (see the next section), then ``getSalt()`` should
+    return ``null``, so that Bcrypt generates the salt itself.
+
+    However, if you use an encoder that does *not* have a built-in salting
+    ability (e.g. ``sha512``), you *must* (from a security perspective) generate
+    your own, random salt, store it on a ``salt`` property that is saved to
+    the database, and return it from ``getSalt()``. Some of the code needed
+    is commented out in the above example.
+
 Authenticating Someone against a Database
 -----------------------------------------
 
@@ -311,6 +324,8 @@ the database to be encoded using this encoder. For details on how to create
 a new User object with a properly encoded password, see the
 :ref:`book-security-encoding-user-password` section of the security chapter.
 
+.. include:: /cookbook/security/_ircmaxwell_password-compat.rst.inc
+
 The ``providers`` section defines an ``administrators`` user provider. A
 user provider is a "source" of where users are loaded during authentication.
 In this case, the ``entity`` keyword means that Symfony will use the Doctrine