Skip to content

Update recommended password encoder to "auto" #11767

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 24, 2019
Merged

Update recommended password encoder to "auto" #11767

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 4 additions & 8 deletions best_practices/security.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <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:
Expand All @@ -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:
Expand Down
36 changes: 18 additions & 18 deletions reference/configuration/security.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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"
/>

Expand Down Expand Up @@ -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,
],

Expand Down Expand Up @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Imho, we should keep this section, it is just talking about the BCrypt algorithm, and instead add a new section for the auto password encoder.

Copy link
Member

@chalasr chalasr Aug 18, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The bcrypt encoder has been deprecated though. Also technically speaking auto is not an encoder, it's only a possible value for the algorithm config option which saves from having to choose between native and sodium. So I'm not fond of documenting it this way neither.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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.

Expand All @@ -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
Expand Down
7 changes: 4 additions & 3 deletions security.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -142,7 +143,7 @@ command will pre-configure this for you:
<!-- ... -->

<encoder class="App\Entity\User"
algorithm="bcrypt"
algorithm="auto"
cost="12"/>

<!-- ... -->
Expand All @@ -157,7 +158,7 @@ command will pre-configure this for you:

'encoders' => [
'App\Entity\User' => [
'algorithm' => 'bcrypt',
'algorithm' => 'auto',
'cost' => 12,
]
],
Expand Down
16 changes: 8 additions & 8 deletions security/named_encoders.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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>
Expand All @@ -47,7 +47,7 @@ to apply to all instances of a specific class:
// ...
'encoders' => [
User::class => [
'algorithm' => 'bcrypt',
'algorithm' => 'auto',
'cost' => 12,
],
],
Expand All @@ -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::
Expand All @@ -70,7 +70,7 @@ be done with named encoders:
# ...
encoders:
harsh:
algorithm: bcrypt
algorithm: auto
cost: 15

.. code-block:: xml
Expand All @@ -87,7 +87,7 @@ be done with named encoders:
<config>
<!-- ... -->
<encoder class="harsh"
algorithm="bcrypt"
algorithm="auto"
cost="15"/>
</config>
</srv:container>
Expand All @@ -99,7 +99,7 @@ be done with named encoders:
// ...
'encoders' => [
'harsh' => [
'algorithm' => 'bcrypt',
'algorithm' => 'auto',
'cost' => '15',
],
],
Expand Down
6 changes: 3 additions & 3 deletions security/user_provider.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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>
Expand All @@ -257,7 +257,7 @@ users will encode their passwords:
// ...
'encoders' => [
User::class => [
'algorithm' => 'bcrypt',
'algorithm' => 'auto',
],
],
]);
Expand Down