Password Hashing and Verification

Configure a new Hasher Using "migrate_from"

When a better hashing algorithm becomes available, you should keep the existing hasher(s), rename it, and then define the new one. Set the migrate_from option on the new hasher to point to the old, legacy hasher(s):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# config/packages/security.yaml
security:
    # ...

    password_hashers:
        # a hasher used in the past for some users
        legacy:
            algorithm: sha256
            encode_as_base64: false
            iterations: 1

        App\Entity\User:
            # the new hasher, along with its options
            algorithm: sodium
            migrate_from:
                - bcrypt # uses the "bcrypt" hasher with the default options
                - legacy # uses the "legacy" hasher configured above

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

<!-- config/packages/security.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:security="http://symfony.com/schema/dic/security"
    xsi:schemaLocation="http://symfony.com/schema/dic/security
        https://symfony.com/schema/dic/security/security-1.0.xsd
        http://symfony.com/schema/dic/security
        https://symfony.com/schema/dic/security/security-1.0.xsd">

    <security:config>
        <!-- ... -->

        <security:password-hasher class="legacy"
            algorithm="sha256"
            encode-as-base64="false"
            iterations="1"
        />

        <!-- algorithm: the new hasher, along with its options -->
        <security:password-hasher class="App\Entity\User"
            algorithm="sodium"
        >
            <!-- uses the bcrypt hasher with the default options -->
            <security:migrate-from>bcrypt</security:migrate-from>

            <!-- uses the legacy hasher configured above -->
            <security:migrate-from>legacy</security:migrate-from>
        </security:password-hasher>
    </security:config>
</container>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

// config/packages/security.php
use Symfony\Config\SecurityConfig;

return static function (SecurityConfig $security): void {
    // ...
    $security->passwordHasher('legacy')
        ->algorithm('sha256')
        ->encodeAsBase64(true)
        ->iterations(1)
    ;

    $security->passwordHasher('App\Entity\User')
        // the new hasher, along with its options
        ->algorithm('sodium')
        ->migrateFrom([
            'bcrypt', // uses the "bcrypt" hasher with the default options
            'legacy', // uses the "legacy" hasher configured above
        ])
    ;
};

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

// ...
$passwordHasherFactory = new PasswordHasherFactory([
    'legacy' => [
        'algorithm' => 'sha256',
        'encode_as_base64' => true,
        'iterations' => 1,
    ],

    User::class => [
        // the new hasher, along with its options
        'algorithm' => 'sodium',
        'migrate_from' => [
            'bcrypt', // uses the "bcrypt" hasher with the default options
            'legacy', // uses the "legacy" hasher configured above
        ],
    ],
]);

With this setup:

• New users will be hashed 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.

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. When using a custom authenticator, you must use the PasswordCredentials in the security passport.

You can enable the upgrade behavior by implementing how this newly hashed password should be stored:

• When using Doctrine's entity user provider
• When using a custom user provider

After this, you're done and passwords are always hashed as securely as possible!

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

// src/Repository/UserRepository.php
namespace App\Repository;

// ...
use Symfony\Component\Security\Core\User\PasswordAuthenticatedUserInterface;
use Symfony\Component\Security\Core\User\PasswordUpgraderInterface;

class UserRepository extends EntityRepository implements PasswordUpgraderInterface
{
    // ...

    public function upgradePassword(PasswordAuthenticatedUserInterface $user, string $newHashedPassword): void
    {
        // set the new hashed password on the User object
        $user->setPassword($newHashedPassword);

        // execute the queries on the database
        $this->getEntityManager()->flush();
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

// 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 $newHashedPassword): void
    {
        // set the new hashed password on the User object
        $user->setPassword($newHashedPassword);

        // ... store the new password
    }
}

Trigger Password Migration From a Custom Hasher

If you're using a custom password hasher, you can trigger the password migration by returning true in the needsRehash() method:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

// src/Security/CustomPasswordHasher.php
namespace App\Security;

// ...
use Symfony\Component\PasswordHasher\PasswordHasherInterface;

class CustomPasswordHasher implements PasswordHasherInterface
{
    // ...

    public function needsRehash(string $hashedPassword): bool
    {
        // check whether the current password is hashed using an outdated hasher
        $hashIsOutdated = ...;

        return $hashIsOutdated;
    }
}

The "auto" Hasher

It automatically selects the best available hasher (currently Bcrypt). If PHP or Symfony adds new password hashers in the future, it might select a different hasher.

Because of this, the length of the hashed passwords may change in the future, so make sure to allocate enough space for them to be persisted (varchar(255) should be a good setting).

The Bcrypt Password Hasher

It produces hashed passwords with the bcrypt password hashing function. Hashed passwords are 60 characters long, so make sure to allocate enough space for them to be persisted. Also, passwords include the cryptographic salt inside them (it's generated automatically for each new password) so you don't have to deal with it.

Its only configuration option is cost, which is an integer in the range of 4-31 (by default, 13). Each single increment of the cost doubles the time it takes to hash a password. It's designed this way so the password strength can be adapted to the future improvements in computation power.

You can change the cost at any time — even if you already have some passwords hashed using a different cost. New passwords will be hashed using the new cost, while the already hashed ones will be validated using a cost that was used back when they were hashed.

The Sodium Password Hasher

It uses the Argon2 key derivation function. Argon2 support was introduced in PHP 7.2 by bundling the libsodium extension.

The hashed passwords are 96 characters long, but due to the hashing requirements saved in the resulting hash this may change in the future, so make sure to allocate enough space for them to be persisted. Also, passwords include the cryptographic salt inside them (it's generated automatically for each new password) so you don't have to deal with it.

The PBKDF2 Hasher

Using the PBKDF2 hasher is no longer recommended since PHP added support for Sodium and BCrypt. Legacy application still using it are encouraged to upgrade to those newer hashing algorithms.

Creating a custom Password Hasher

If you need to create your own, it needs to follow these rules:

1. The class must implement PasswordHasherInterface (you can also implement LegacyPasswordHasherInterface if your hash algorithm uses a separate salt);

2. The implementations of hash() and verify() must validate that the password length is no longer than 4096 characters. This is for security reasons (see CVE-2013-5750).

   You can use the isPasswordTooLong() method for this check.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

// src/Security/Hasher/CustomVerySecureHasher.php
namespace App\Security\Hasher;

use Symfony\Component\PasswordHasher\Exception\InvalidPasswordException;
use Symfony\Component\PasswordHasher\Hasher\CheckPasswordLengthTrait;
use Symfony\Component\PasswordHasher\PasswordHasherInterface;

class CustomVerySecureHasher implements PasswordHasherInterface
{
    use CheckPasswordLengthTrait;

    public function hash(string $plainPassword): string
    {
        if ($this->isPasswordTooLong($plainPassword)) {
            throw new InvalidPasswordException();
        }

        // ... hash the plain password in a secure way

        return $hashedPassword;
    }

    public function verify(string $hashedPassword, string $plainPassword): bool
    {
        if ('' === $plainPassword || $this->isPasswordTooLong($plainPassword)) {
            return false;
        }

        // ... validate if the password equals the user's password in a secure way

        return $passwordIsValid;
    }

    public function needsRehash(string $hashedPassword): bool
    {
        // Check if a password hash would benefit from rehashing
        return $needsRehash;
    }
}

Now, define a password hasher using the id setting:

1
2
3
4
5
6
7

# config/packages/security.yaml
security:
    # ...
    password_hashers:
        app_hasher:
            # the service ID of your custom hasher (the FQCN using the default services.yaml)
            id: 'App\Security\Hasher\MyCustomPasswordHasher'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

<!-- 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
        http://symfony.com/schema/dic/security
        https://symfony.com/schema/dic/security/security-1.0.xsd"
>

    <config>
        <!-- ... -->
        <!-- id: the service ID of your custom hasher (the FQCN using the default services.yaml) -->
        <security:password_hasher class="app_hasher"
            id="App\Security\Hasher\CustomVerySecureHasher"/>
    </config>
</srv:container>

1
2
3
4
5
6
7
8
9
10
11

// config/packages/security.php
use App\Security\Hasher\CustomVerySecureHasher;
use Symfony\Config\SecurityConfig;

return static function (SecurityConfig $security): void {
    // ...
    $security->passwordHasher('app_hasher')
        // the service ID of your custom hasher (the FQCN using the default services.yaml)
        ->id(CustomVerySecureHasher::class)
    ;
};