Merge branch '4.3' into 4.4

* 4.3:
  Update recommended password encoder to \"auto\"

Author: javiereguiluz

best_practices/security.rst

@@ -29,20 +29,13 @@ site (or maybe nearly *all* sections), use the ``access_control`` area.
 
 .. best-practice::
 
-    Use the ``bcrypt`` encoder for hashing your users' passwords.
-
-If your users have a password, then we recommend hashing it using the ``bcrypt``
-encoder, instead of the traditional SHA-512 hashing encoder. The main advantages
-of ``bcrypt`` are the inclusion of a *salt* value to protect against rainbow
-table attacks, and its adaptive nature, which allows to make it slower to
-remain resistant to brute-force search attacks.
+    Use the ``auto`` encoder for hashing your users' passwords.
 
 .. note::
 
     :ref:`Sodium <reference-security-sodium>` is the hashing algorithm as
     recommended by industry standards, but this won't be available to you unless
     you are using PHP 7.2+ or have the `libsodium`_ extension installed.
-    ``bcrypt`` is sufficient for most applications.
 
 With this in mind, here is the authentication setup from our application,
 which uses a login form to load users from the database:
@@ -52,7 +45,7 @@ which uses a login form to load users from the database:
     # config/packages/security.yaml
     security:
         encoders:
-            App\Entity\User: bcrypt
+            App\Entity\User: auto
 
         providers:
             database_users:

reference/configuration/security.rst

@@ -129,12 +129,12 @@ encoding algorithm. Also, each algorithm defines different config options:
             # ...
 
             encoders:
-                # bcrypt encoder with default options
-                App\Entity\User: 'bcrypt'
+                # auto encoder with default options
+                App\Entity\User: 'auto'
 
-                # bcrypt encoder with custom options
+                # auto encoder with custom options
                 App\Entity\User:
-                    algorithm: 'bcrypt'
+                    algorithm: 'auto'
                     cost:      15
 
                 # Sodium encoder with default options
@@ -162,16 +162,16 @@ encoding algorithm. Also, each algorithm defines different config options:
 
             <config>
                 <!-- ... -->
-                <!-- bcrypt encoder with default options -->
+                <!-- auto encoder with default options -->
                 <encoder
                     class="App\Entity\User"
-                    algorithm="bcrypt"
+                    algorithm="auto"
                 />
 
-                <!-- bcrypt encoder with custom options -->
+                <!-- auto encoder with custom options -->
                 <encoder
                     class="App\Entity\User"
-                    algorithm="bcrypt"
+                    algorithm="auto"
                     cost="15"
                 />
 
@@ -209,14 +209,14 @@ encoding algorithm. Also, each algorithm defines different config options:
         $container->loadFromExtension('security', [
             // ...
             'encoders' => [
-                // bcrypt encoder with default options
+                // auto encoder with default options
                 User::class => [
-                    'algorithm' => 'bcrypt',
+                    'algorithm' => 'auto',
                 ],
 
-                // bcrypt encoder with custom options
+                // auto encoder with custom options
                 User::class => [
-                    'algorithm' => 'bcrypt',
+                    'algorithm' => 'auto',
                     'cost'      => 15,
                 ],
 
@@ -278,16 +278,20 @@ 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-bcrypt:
+.. _reference-security-encoder-auto:
 
-Using the BCrypt Password Encoder
+Using the "auto" Password Encoder
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-It uses the `bcrypt password hashing function`_ and it's recommended to use it
-when it's not possible to use Sodium. The encoded 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.
+It selects automatically the best possible encoder. 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
+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
@@ -311,7 +315,7 @@ Using the PBKDF2 Encoder
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 Using the `PBKDF2`_ encoder is no longer recommended since PHP added support for
-Sodium and bcrypt. Legacy application still using it are encouraged to upgrade
+Sodium and BCrypt. Legacy application still using it are encouraged to upgrade
 to those newer encoding algorithms.
 
 firewalls

security.rst

@@ -125,7 +125,8 @@ command will pre-configure this for you:
                 # use your user class name here
                 App\Entity\User:
                     # Use native password encoder
-                    # This value auto-selects the best possible hashing algorithm.
+                    # This value auto-selects the best possible hashing algorithm
+                    # (i.e. Sodium when available).
                     algorithm: auto
 
     .. code-block:: xml
@@ -142,7 +143,7 @@ command will pre-configure this for you:
                 <!-- ... -->
 
                 <encoder class="App\Entity\User"
-                    algorithm="bcrypt"
+                    algorithm="auto"
                     cost="12"/>
 
                 <!-- ... -->
@@ -157,7 +158,7 @@ command will pre-configure this for you:
 
             'encoders' => [
                 'App\Entity\User' => [
-                    'algorithm' => 'bcrypt',
+                    'algorithm' => 'auto',
                     'cost' => 12,
                 ]
             ],

security/named_encoders.rst

@@ -16,7 +16,7 @@ to apply to all instances of a specific class:
             # ...
             encoders:
                 App\Entity\User:
-                    algorithm: bcrypt
+                    algorithm: auto
                     cost: 12
 
     .. code-block:: xml
@@ -32,7 +32,7 @@ to apply to all instances of a specific class:
             <config>
                 <!-- ... -->
                 <encoder class="App\Entity\User"
-                    algorithm="bcrypt"
+                    algorithm="auto"
                     cost=12
                 />
             </config>
@@ -47,7 +47,7 @@ to apply to all instances of a specific class:
             // ...
             'encoders' => [
                 User::class => [
-                    'algorithm' => 'bcrypt',
+                    'algorithm' => 'auto',
                     'cost' => 12,
                 ],
             ],
@@ -56,9 +56,9 @@ to apply to all instances of a specific class:
 Another option is to use a "named" encoder and then select which encoder
 you want to use dynamically.
 
-In the previous example, you've set the ``bcrypt`` algorithm for ``App\Entity\User``.
+In the previous example, you've set the ``auto`` algorithm for ``App\Entity\User``.
 This may be secure enough for a regular user, but what if you want your admins
-to have a stronger algorithm, for example ``bcrypt`` with a higher cost. This can
+to have a stronger algorithm, for example ``auto`` with a higher cost. This can
 be done with named encoders:
 
 .. configuration-block::
@@ -70,7 +70,7 @@ be done with named encoders:
             # ...
             encoders:
                 harsh:
-                    algorithm: bcrypt
+                    algorithm: auto
                     cost: 15
 
     .. code-block:: xml
@@ -87,7 +87,7 @@ be done with named encoders:
             <config>
                 <!-- ... -->
                 <encoder class="harsh"
-                    algorithm="bcrypt"
+                    algorithm="auto"
                     cost="15"/>
             </config>
         </srv:container>
@@ -99,7 +99,7 @@ be done with named encoders:
             // ...
             'encoders' => [
                 'harsh' => [
-                    'algorithm' => 'bcrypt',
+                    'algorithm' => 'auto',
                     'cost'      => '15',
                 ],
             ],

security/user_provider.rst

@@ -224,7 +224,7 @@ users will encode their passwords:
             # ...
             encoders:
                 # this internal class is used by Symfony to represent in-memory users
-                Symfony\Component\Security\Core\User\User: 'bcrypt'
+                Symfony\Component\Security\Core\User\User: 'auto'
 
     .. code-block:: xml
 
@@ -241,7 +241,7 @@ users will encode their passwords:
 
                 <!-- this internal class is used by Symfony to represent in-memory users -->
                 <encoder class="Symfony\Component\Security\Core\User\User"
-                    algorithm="bcrypt"
+                    algorithm="auto"
                 />
             </config>
         </srv:container>
@@ -257,7 +257,7 @@ users will encode their passwords:
             // ...
             'encoders' => [
                 User::class => [
-                    'algorithm' => 'bcrypt',
+                    'algorithm' => 'auto',
                 ],
             ],
         ]);