Skip to content

tweaking the password upgrading functionality #12960

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jan 21, 2020
Merged

tweaking the password upgrading functionality #12960

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 16 additions & 9 deletions security/password_migration.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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::

Expand All @@ -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
Expand Down Expand Up @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Symfony will verify the password with the old algorithm and then re-encode
Symfony will verify the password with the old algorithm and then rehash

Confusing Symfony terminology, but the password encoders are doing hashing. This is also consistent with earlier uses of "rehash(ing)" in the beginning of this chapter.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I made this change while merging.

and update the hashed password using the new algorithm.

.. tip::

The *auto*, *native*, *bcrypt* and *argon* encoders automatically enable
Expand All @@ -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.

Expand Down