symfony
diff --git a/‎security.rst
Copy file name to clipboardExpand all lines: security.rst
+1Lines changed: 1 addition & 0 deletions b/‎security.rst
Copy file name to clipboardExpand all lines: security.rst
+1Lines changed: 1 addition & 0 deletions
diff --git a/‎security/migrating_password_hashes.rst
Copy file name to clipboard
+182Lines changed: 182 additions & 0 deletions b/‎security/migrating_password_hashes.rst
Copy file name to clipboard
+182Lines changed: 182 additions & 0 deletions
@@ -987,6 +987,7 @@ Authentication (Identifying/Logging in the User)
 
     security/form_login_setup
     security/guard_authentication
+    security/migrating_password_hashes
     security/auth_providers
     security/user_provider
     security/ldap
 
@@ -0,0 +1,182 @@
+.. index::
+    single: Security; How to Migrate a Password Hash
+
+How to Migrate a Password Hash
+==============================
+
+.. versionadded:: 4.4
+
+    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 succesfully authenticated.
+
+To enable this, make sure you apply the following steps to your application:
+
+#. `Configure the "auto" Encoder`_
+#. `Upgrade the Password`_
+#. Optionally, `Trigger Password Migration From a Custom Encoder`_
+
+Configure the "auto" Encoder
+----------------------------
+
+The "auto" encoder is able to verify the hash of a number of different
+algorithms and can also hash new plain text passwords.
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/security.yaml
+        security:
+            # ...
+
+            encoders:
+                App\Entity\User:
+                    algorithm: auto
+                    cost: 14
+
+    .. code-block:: xml
+
+        <!-- config/packages/security.xml -->
+        <?xml version="1.0" encoding="UTF-8"?>
+        <srv:container xmlns="http://symfony.com/schema/dic/security"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:srv="http://symfony.com/schema/dic/services"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <config>
+                <!-- ... -->
+
+                <encoder class="App\Entity\User"
+                    algorithm="auto"
+                    cost="14"/>
+
+                <!-- ... -->
+            </config>
+        </srv:container>
+
+    .. code-block:: php
+
+        // config/packages/security.php
+        $container->loadFromExtension('security', [
+            // ...
+
+            'encoders' => [
+                'App\Entity\User' => [
+                    'algorithm' => 'auto',
+                    'cost' => 14,
+                ]
+            ],
+
+            // ...
+        ]);
+
+The auto encoder does this by using a list of encoders. The first algorithm in
+the list is used to hash new passwords. It is configured to use the following algorithms:
+
+#. :ref:`Sodium <reference-security-sodium>` when available, otherwise native is used (which uses :phpfunction:`password_hash`);
+#. :ref:`PBKDF2 <reference-security-pbkdf2>` (which uses :phpfunction:`hash_pbkdf2`);
+#. The configured encoder in ``hash_algorithm``.
+
+If you previously used the bcrypt encoder, they are supported through the
+Sodium and Native encoders. Any custom encoder previously used can be
+configured by setting ``hash_algorithm`` to the custom encoder name.
+
+Upgrade the Password
+--------------------
+
+Upon successful login, the Security system checks whether a better algorithm
+is available to hash the user's password. If it is, it'll hash the correct
+password using the new hash. You can enable this behavior by implementing how
+this newly hashed password should be stored:
+
+* `When using Doctrine's entity user provider <Upgrade the Password when using Doctrine>`_ 
+* `When using a custom user provider <Upgrade the Password when using a custom User Provider>`_ 
+
+After this, you're done and passwords are always hashed as secure as possible!
+
+Upgrade the Password when using Doctrine
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When using the :ref:`entity user provider <security-entity-user-provider>`, implement
+:class:`Symfony\\Component\\Security\\Core\\User\\PasswordUpgraderInterface` in
+the ``UserRepository`` (see `the Doctrine docs for information`_ on how to
+create this class if it's not already created). This interface implements
+storing the newly created password hash::
+
+    // src/Repository/UserRepository.php
+    namespace App\Repository;
+
+    // ...
+    use Symfony\Component\Security\Core\User\PasswordUpgraderInterface;
+
+    class UserRepository extends EntityRepository implements PasswordUpgraderInterface
+    {
+        // ...
+
+        public function upgradePassword(UserInterface $user, string $newEncodedPassword): void
+        {
+            // set the new encoded password on the User object
+            $user->setPassword($newEncodedPassword);
+
+            // execute the queries on the database
+            $this->getEntityManager->flush($user);
+        }
+    }
+
+Upgrade the Password when using a custom User Provider
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you're using a :ref:`custom user provider <custom-user-provider>`, implement the
+:class:`Symfony\\Component\\Security\\Core\\User\\PasswordUpgraderInterface` in
+the user provider::
+
+    // src/Security/UserProvider.php
+    namespace App\Security;
+
+    // ...
+    use Symfony\Component\Security\Core\User\PasswordUpgraderInterface;
+
+    class UserProvider implements UserProviderInterface, PasswordUpgraderInterface
+    {
+        // ...
+
+        public function upgradePassword(UserInterface $user, string $newEncodedPassword): void
+        {
+            // set the new encoded password on the User object
+            $user->setPassword($newEncodedPassword);
+
+            // ... store the new password
+        }
+    }
+
+Trigger Password Migration From a Custom Encoder
+------------------------------------------------
+
+If you're using a custom password encoder, you can trigger the password
+migration by returning ``true`` in the ``needsRehash()`` method::
+
+    // src/Security/UserProvider.php
+    namespace App\Security;
+
+    // ...
+    use Symfony\Component\Security\Core\Encoder\PasswordEncoderInterface;
+
+    class CustomPasswordEncoder implements PasswordEncoderInterface
+    {
+        // ...
+
+        public function needsRehash(string $encoded): bool
+        {
+            // check whether the current password is hash using an outdated encoder
+            $hashIsOutdated = ...;
+
+            return $hashIsOutdated;
+        }
+    }
+
+.. _`the Doctrine docs for information`: https://www.doctrine-project.org/projects/doctrine-orm/en/current/reference/working-with-objects.html#custom-repositories