diff --git a/best_practices/security.rst b/best_practices/security.rst index bd68fb21b4d..fe51a879fab 100644 --- a/best_practices/security.rst +++ b/best_practices/security.rst @@ -29,20 +29,16 @@ site (or maybe nearly *all* sections), use the ``access_control`` area. .. best-practice:: - Use the ``bcrypt`` encoder for hashing your users' passwords. + Use the ``auto`` 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. +If your users have a password, then we recommend hashing it using the ``auto`` +encoder. .. note:: :ref:`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 +48,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: diff --git a/reference/configuration/security.rst b/reference/configuration/security.rst index 82341f04cee..f141f2bd875 100644 --- a/reference/configuration/security.rst +++ b/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: - + - + @@ -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,14 +278,14 @@ 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. +It uses Sodium as default, falling back to the `bcrypt password hashing function`_, +which 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. @@ -311,7 +311,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 diff --git a/security.rst b/security.rst index ad20d0df512..f54990ef294 100644 --- a/security.rst +++ b/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: @@ -157,7 +158,7 @@ command will pre-configure this for you: 'encoders' => [ 'App\Entity\User' => [ - 'algorithm' => 'bcrypt', + 'algorithm' => 'auto', 'cost' => 12, ] ], diff --git a/security/named_encoders.rst b/security/named_encoders.rst index 462ade3a1da..aad4d740fb1 100644 --- a/security/named_encoders.rst +++ b/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: @@ -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: @@ -99,7 +99,7 @@ be done with named encoders: // ... 'encoders' => [ 'harsh' => [ - 'algorithm' => 'bcrypt', + 'algorithm' => 'auto', 'cost' => '15', ], ], diff --git a/security/user_provider.rst b/security/user_provider.rst index e4628a7ec31..e7919f389d9 100644 --- a/security/user_provider.rst +++ b/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: @@ -257,7 +257,7 @@ users will encode their passwords: // ... 'encoders' => [ User::class => [ - 'algorithm' => 'bcrypt', + 'algorithm' => 'auto', ], ], ]);