[Security] Renamed encoders to password_hashers

Author: javiereguiluz

reference/configuration/security.rst

@@ -40,7 +40,7 @@ Some of these options define tens of sub-options and they are explained in
 separate articles:
 
 * `access_control`_
-* `encoders`_
+* `hashers`_
 * `firewalls`_
 * `providers`_
 * `role_hierarchy`_
@@ -120,15 +120,16 @@ and to allow anonymous users to the login form page.
 
 This option is explained in detail in :doc:`/security/access_control`.
 
-encoders
---------
+.. _encoders:
 
-This option defines the algorithm used to *encode* the password of the users.
-Although Symfony calls it *"password encoding"* for historical reasons, this is
-in fact, *"password hashing"*.
+hashers
+-------
+
+This option defines the algorithm used to *hash* the password of the users
+(which in previous Symfony versions was wrongly called *"password encoding"*).
 
 If your app defines more than one user class, each of them can define its own
-encoding algorithm. Also, each algorithm defines different config options:
+hashing algorithm. Also, each algorithm defines different config options:
 
 .. configuration-block::
 
@@ -138,25 +139,25 @@ encoding algorithm. Also, each algorithm defines different config options:
         security:
             # ...
 
-            encoders:
-                # auto encoder with default options
+            password_hashers:
+                # auto hasher with default options
                 App\Entity\User: 'auto'
 
-                # auto encoder with custom options
+                # auto hasher with custom options
                 App\Entity\User:
                     algorithm: 'auto'
                     cost:      15
 
-                # Sodium encoder with default options
+                # Sodium hasher with default options
                 App\Entity\User: 'sodium'
 
-                # Sodium encoder with custom options
+                # Sodium hasher with custom options
                 App\Entity\User:
                     algorithm:   'sodium'
                     memory_cost:  16384 # Amount in KiB. (16384 = 16 MiB)
                     time_cost:    2     # Number of iterations
 
-                # MessageDigestPasswordEncoder encoder using SHA512 hashing with default options
+                # MessageDigestPasswordHasher hasher using SHA512 hashing with default options
                 App\Entity\User: 'sha512'
 
     .. code-block:: xml
@@ -173,37 +174,37 @@ encoding algorithm. Also, each algorithm defines different config options:
 
             <config>
                 <!-- ... -->
-                <!-- auto encoder with default options -->
-                <encoder
+                <!-- auto hasher with default options -->
+                <security:password-hasher
                     class="App\Entity\User"
                     algorithm="auto"
                 />
 
-                <!-- auto encoder with custom options -->
-                <encoder
+                <!-- auto hasher with custom options -->
+                <security:password-hasher
                     class="App\Entity\User"
                     algorithm="auto"
                     cost="15"
                 />
 
-                <!-- Sodium encoder with default options -->
-                <encoder
+                <!-- Sodium hasher with default options -->
+                <security:password-hasher
                     class="App\Entity\User"
                     algorithm="sodium"
                 />
 
-                <!-- Sodium encoder with custom options -->
+                <!-- Sodium hasher with custom options -->
                 <!-- memory_cost: amount in KiB. (16384 = 16 MiB)
                      time_cost: number of iterations -->
-                <encoder
+                <security:password-hasher
                     class="App\Entity\User"
                     algorithm="sodium"
                     memory_cost="16384"
                     time_cost="2"
                 />
 
-                <!-- MessageDigestPasswordEncoder encoder using SHA512 hashing with default options -->
-                <encoder
+                <!-- MessageDigestPasswordHasher hasher using SHA512 hashing with default options -->
+                <security:password-hasher
                     class="App\Entity\User"
                     algorithm="sha512"
                 />
@@ -217,55 +218,61 @@ encoding algorithm. Also, each algorithm defines different config options:
 
         $container->loadFromExtension('security', [
             // ...
-            'encoders' => [
-                // auto encoder with default options
+            'password_hashers' => [
+                // auto hasher with default options
                 User::class => [
                     'algorithm' => 'auto',
                 ],
 
-                // auto encoder with custom options
+                // auto hasher with custom options
                 User::class => [
                     'algorithm' => 'auto',
                     'cost'      => 15,
                 ],
 
-                // Sodium encoder with default options
+                // Sodium hasher with default options
                 User::class => [
                     'algorithm' => 'sodium',
                 ],
 
-                // Sodium encoder with custom options
+                // Sodium hasher with custom options
                 User::class => [
                     'algorithm' => 'sodium',
                     'memory_cost' => 16384, // Amount in KiB. (16384 = 16 MiB)
                     'time_cost' => 2,       // Number of iterations
                 ],
 
-                // MessageDigestPasswordEncoder encoder using SHA512 hashing with default options
+                // MessageDigestPasswordHasher hasher using SHA512 hashing with default options
                 User::class => [
                     'algorithm' => 'sha512',
                 ],
             ],
         ]);
 
+.. versionadded:: 5.3
+
+    The ``password_hashers`` option was introduced in Symfony 5.3. In previous
+    versions it was called ``encoders``.
+
 .. tip::
 
-    You can also create your own password encoders as services and you can even
-    select a different password encoder for each user instance. Read
+    You can also create your own password hashers as services and you can even
+    select a different password hasher for each user instance. Read
     :doc:`this article </security/named_encoders>` for more details.
 
 .. tip::
 
-    Encoding passwords is resource intensive and takes time in order to generate
+    Hashing passwords is resource intensive and takes time in order to generate
     secure password hashes. In tests however, secure hashes are not important, so
-    you can change the encoders configuration in ``test`` environment to run tests faster:
+    you can change the password hasher configuration in ``test`` environment to
+    run tests faster:
 
     .. configuration-block::
 
         .. code-block:: yaml
 
             # config/packages/test/security.yaml
-            encoders:
+            password_hashers:
                 # Use your user class name here
                 App\Entity\User:
                     algorithm: auto # This should be the same value as in config/packages/security.yaml
@@ -289,7 +296,7 @@ encoding algorithm. Also, each algorithm defines different config options:
                     <!-- cost: Lowest possible value for bcrypt -->
                     <!-- time_cost: Lowest possible value for argon -->
                     <!-- memory_cost: Lowest possible value for argon -->
-                    <encoder
+                    <security:password-hasher
                         class="App\Entity\User"
                         algorithm="auto"
                         cost="4"
@@ -305,7 +312,7 @@ encoding algorithm. Also, each algorithm defines different config options:
             use App\Entity\User;
 
             $container->loadFromExtension('security', [
-                'encoders' => [
+                'password_hashers' => [
                     // Use your user class name here
                     User::class => [
                         'algorithm' => 'auto', // This should be the same value as in config/packages/security.yaml
@@ -318,44 +325,46 @@ encoding algorithm. Also, each algorithm defines different config options:
 
 .. _reference-security-sodium:
 .. _using-the-argon2i-password-encoder:
+.. _using-the-sodium-password-encoder:
 
-Using the Sodium Password Encoder
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Using the Sodium Password Hasher
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-It uses the `Argon2 key derivation function`_ and it's the encoder recommended
+It uses the `Argon2 key derivation function`_ and it's the hasher recommended
 by Symfony. Argon2 support was introduced in PHP 7.2, but if you use an earlier
 PHP version, you can install the `libsodium`_ PHP extension.
 
-The encoded passwords are ``96`` characters long, but due to the hashing
+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.
 
 .. _reference-security-encoder-auto:
+.. _using-the-auto-password-encoder:
 
-Using the "auto" Password Encoder
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Using the "auto" Password Hasher
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-It selects automatically the best possible encoder. Currently, it tries to use
+It selects automatically the best possible hasher. Currently, it tries to use
 Sodium by default and falls back to the `bcrypt password hashing function`_ if
 not possible. In the future, when PHP adds new hashing techniques, it may use
 different password hashers.
 
-It produces encoded passwords with ``60`` characters long, so make sure to
+It produces hashed passwords with ``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 encode a password. It's designed this way so the password
+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
-encoded using a different cost. New passwords will be encoded using the new
-cost, while the already encoded ones will be validated using a cost that was
-used back when they were encoded.
+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.
 
 .. tip::
 
@@ -364,13 +373,14 @@ used back when they were encoded.
     environment configuration.
 
 .. _reference-security-pbkdf2:
+.. _using-the-pbkdf2-encoder:
 
-Using the PBKDF2 Encoder
-~~~~~~~~~~~~~~~~~~~~~~~~
+Using the PBKDF2 Hasher
+~~~~~~~~~~~~~~~~~~~~~~~
 
-Using the `PBKDF2`_ encoder is no longer recommended since PHP added support for
+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 encoding algorithms.
+to those newer hashing algorithms.
 
 firewalls
 ---------

security.rst

@@ -200,12 +200,13 @@ here: :doc:`User Providers </security/user_provider>`.
 
 .. _security-encoding-user-password:
 .. _encoding-the-user-s-password:
+.. _2c-encoding-passwords:
 
-2c) Encoding Passwords
-----------------------
+2c) Hashing Passwords
+---------------------
 
 Not all applications have "users" that need passwords. *If* your users have passwords,
-you can control how those passwords are encoded in ``security.yaml``. The ``make:user``
+you can control how those passwords are hashed in ``security.yaml``. The ``make:user``
 command will pre-configure this for you:
 
 .. configuration-block::
@@ -216,10 +217,10 @@ command will pre-configure this for you:
         security:
             # ...
 
-            encoders:
+            password_hashers:
                 # use your user class name here
                 App\Entity\User:
-                    # Use native password encoder, which auto-selects the best
+                    # Use native password hasher, which auto-selects the best
                     # possible hashing algorithm (starting from Symfony 5.3 this is "bcrypt")
                     algorithm: auto
 
@@ -238,7 +239,7 @@ command will pre-configure this for you:
             <config>
                 <!-- ... -->
 
-                <encoder class="App\Entity\User"
+                <security:password-hasher class="App\Entity\User"
                     algorithm="auto"
                     cost="12"/>
 
@@ -254,7 +255,7 @@ command will pre-configure this for you:
         $container->loadFromExtension('security', [
             // ...
 
-            'encoders' => [
+            'password_hashers' => [
                 User::class => [
                     'algorithm' => 'auto',
                     'cost' => 12,
@@ -264,8 +265,13 @@ command will pre-configure this for you:
             // ...
         ]);
 
-Now that Symfony knows *how* you want to encode the passwords, you can use the
-``UserPasswordEncoderInterface`` service to do this before saving your users to
+.. versionadded:: 5.3
+
+    The ``password_hashers`` option was introduced in Symfony 5.3. In previous
+    versions it was called ``encoders``.
+
+Now that Symfony knows *how* you want to hash the passwords, you can use the
+``UserPasswordHasherInterface`` service to do this before saving your users to
 the database.
 
 .. _user-data-fixture:
@@ -280,30 +286,30 @@ create dummy database users:
     The class name of the fixtures to create (e.g. AppFixtures):
     > UserFixtures
 
-Use this service to encode the passwords:
+Use this service to hash the passwords:
 
 .. code-block:: diff
 
       // src/DataFixtures/UserFixtures.php
 
-    + use Symfony\Component\Security\Core\Encoder\UserPasswordEncoderInterface;
+    + use Symfony\Component\PasswordHasher\Hasher\UserPasswordHasherInterface;
       // ...
 
       class UserFixtures extends Fixture
       {
-    +     private $passwordEncoder;
+    +     private $passwordHasher;
 
-    +     public function __construct(UserPasswordEncoderInterface $passwordEncoder)
+    +     public function __construct(UserPasswordHasherInterface $passwordHasher)
     +     {
-    +         $this->passwordEncoder = $passwordEncoder;
+    +         $this->passwordHasher = $passwordHasher;
     +     }
 
           public function load(ObjectManager $manager)
           {
               $user = new User();
               // ...
 
-    +         $user->setPassword($this->passwordEncoder->encodePassword(
+    +         $user->setPassword($this->passwordHasher->hashPassword(
     +             $user,
     +             'the_new_password'
     +         ));
@@ -312,11 +318,11 @@ Use this service to encode the passwords:
           }
       }
 
-You can manually encode a password by running:
+You can manually hash a password by running:
 
 .. code-block:: terminal
 
-    $ php bin/console security:encode-password
+    $ php bin/console security:hash-password
 
 .. _security-yaml-firewalls:
 .. _security-firewalls: