Merge branch '4.4' into 5.0

* 4.4:
  tweaking the password upgrading functionality

Author: javiereguiluz

security/password_migration.rst

@@ -5,21 +5,20 @@ How to Migrate a Password Hash
 ==============================
 
 In order to protect passwords, it is recommended to store them using the latest
-hash algorithms. This means that if a better hash algorithm is supported on the
-system, the user's password should be rehashed and stored. Symfony provides this
-functionality when a user is successfully authenticated.
-
-To enable this, make sure you apply the following steps to your application:
+hash algorithms. This means that if a better hash algorithm is supported on your
+system, the user's password should be *rehashed* using the newer algorithm and
+stored. That's possible with the ``migrate_from`` option:
 
 #. `Configure a new Encoder Using "migrate_from"`_
 #. `Upgrade the Password`_
 #. Optionally, `Trigger Password Migration From a Custom Encoder`_
 
 Configure a new Encoder Using "migrate_from"
---------------------------------------------
+----------------------------------------------
 
-When configuring a new encoder, you can specify a list of legacy encoders by
-using the ``migrate_from`` option:
+When a better hashing algorithm becomes available, you should keep the existing
+encoder(s), rename it, and then define the new one. Set the ``migrate_from`` option
+on the new encoder to point to the old, legacy encoder(s):
 
 .. configuration-block::
 
@@ -30,6 +29,7 @@ using the ``migrate_from`` option:
             # ...
 
             encoders:
+                # an encoder used in the past for some users
                 legacy:
                     algorithm: sha256
                     encode_as_base64: false
@@ -98,6 +98,13 @@ using the ``migrate_from`` option:
             ],
         ]);
 
+With this setup:
+
+* New users will be encoded with the new algorithm;
+* Whenever a user logs in whose password is still stored using the old algorithm,
+  Symfony will verify the password with the old algorithm and then rehash
+  and update the password using the new algorithm.
+
 .. tip::
 
     The *auto*, *native*, *bcrypt* and *argon* encoders automatically enable
@@ -106,7 +113,7 @@ using the ``migrate_from`` option:
     #. :ref:`PBKDF2 <reference-security-pbkdf2>` (which uses :phpfunction:`hash_pbkdf2`);
     #. Message digest (which uses :phpfunction:`hash`)
 
-    Both use the ``hash_algorithm`` setting as algorithm. It is recommended to
+    Both use the ``hash_algorithm`` setting as the algorithm. It is recommended to
     use ``migrate_from`` instead of ``hash_algorithm``, unless the *auto*
     encoder is used.