tweaking the password upgrading functionality

Author: weaverryan

security/password_migration.rst

@@ -9,21 +9,20 @@ How to Migrate a Password Hash
  Password migration was introduced in Symfony 4.4.
 
 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::
 
@@ -34,6 +33,7 @@ using the ``migrate_from`` option:
  # ...
 
  encoders:
+ # an encoder used in the past for some users
  legacy:
  algorithm: sha256
  encode_as_base64: false
@@ -102,6 +102,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 re-encode
+ and update the hashed password using the new algorithm.
+
 .. tip::
 
  The *auto*, *native*, *bcrypt* and *argon* encoders automatically enable
@@ -110,7 +117,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.