From 94fc0b40b861b20d561a111dcc9274a7f669e3f6 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sat, 18 Jan 2020 15:46:13 -0600 Subject: [PATCH] tweaking the password upgrading functionality --- security/password_migration.rst | 25 ++++++++++++++++--------- 1 file changed, 16 insertions(+), 9 deletions(-) diff --git a/security/password_migration.rst b/security/password_migration.rst index d71e8754275..7f1ddf95bd7 100644 --- a/security/password_migration.rst +++ b/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 ` (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.