8000 minor #8481 Argon2i Password Encoder (zanbaldwin, javiereguiluz) · symfony/symfony-docs@829a06d · GitHub
[go: up one dir, main page]
Skip to content

Commit 829a06d

Browse files
javiereguiluzjaviereguiluz
committed
minor #8481 Argon2i Password Encoder (zanbaldwin, javiereguiluz)
This PR was merged into the 3.4 branch. Discussion ---------- Argon2i Password Encoder | Q | A | | --- | --- | | Doc fix? | no | | New docs? | yes (symfony/symfony#21604) | | Applies to | `3.4` | | Fixed tickets | N/A | Add sections for the Argon2i password encoder. Commits ------- d96fda4 Removed a duplicated reference be4f85c Argon2i Password Encoder
2 parents 2ff3d58 + d96fda4 commit 829a06d

File tree

5 files changed

+84
-7
lines changed

5 files changed

+84
-7
lines changed

‎best_practices/security.rst‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,13 @@ of ``bcrypt`` are the inclusion of a *salt* value to protect against rainbow
3838
table attacks, and its adaptive nature, which allows to make it slower to
3939
remain resistant to brute-force search attacks.
4040

41+
.. note::
42+
43+
:ref:`Argon2i <reference-security-argon2i>` is the hashing algorithm as
44+
recommended by industry standards, but this won't be available to you unless
45+
you are using PHP 7.2+ or have the `libsodium`_ extension installed.
46+
``bcrypt`` is sufficient for most applications.
47+
4148
With this in mind, here is the authentication setup from our application,
4249
which uses a login form to load users from the database:
4350

@@ -397,3 +404,4 @@ Next: :doc:`/best_practices/web-assets`
397404
.. _`ParamConverter`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html
398405
.. _`@Security annotation`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/security.html
399406
.. _`FOSUserBundle`: https://github.com/FriendsOfSymfony/FOSUserBundle
407+
.. _`libsodium`: https://pecl.php.net/package/libsodium

‎doctrine/registration_form.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -132,7 +132,7 @@ With some validation added, your class may look something like this::
132132

133133
public function getSalt()
134134
{
135-
// The bcrypt algorithm doesn't require a separate salt.
135+
// The bcrypt and argon2i algorithms don't require a separate salt.
136136
// You *may* need a real salt if you choose a different encoder.
137137
return null;
138138
}

‎reference/configuration/security.rst‎

Lines changed: 63 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -82,6 +82,10 @@ Each part will be explained in the next section.
8282
algorithm: plaintext
8383
ignore_case: false
8484
85+
# Argon2i encoder
86+
Acme\DemoBundle\Entity\User6:
87+
algorithm: argon2i
88+
8589
providers: # Required
8690
# Examples:
8791
my_in_memory_provider:
@@ -611,7 +615,7 @@ persisting the encoded password alone is enough.
611615

612616
.. note::
613617

614-
All the encoded passwords are ``60`` characters long, so make sure to
618+
BCrypt encoded passwords are ``60`` characters long, so make sure to
615619
allocate enough space for them to be persisted.
616620

617621
.. tip::
@@ -620,7 +624,63 @@ persisting the encoded password alone is enough.
620624
the cost to ``4``, which is the minimum value allowed, in the ``test``
621625
environment configuration.
622626

623-
.. _reference-security-firewall-context:
627+
.. _reference-security-argon2i:
628+
629+
Using the Argon2i Password Encoder
630+
----------------------------------
631+
632+
.. caution::
633+
634+
To use this encoder, you either need to use PHP version 7.2 or install
635+
the `libsodium`_ extension.
636+
637+
.. configuration-block::
638+
639+
.. code-block:: yaml
640+
641+
# app/config/security.yml
642+
security:
643+
# ...
644+
645+
encoders:
646+
Symfony\Component\Security\Core\User\User:
647+
algorithm: argon2i
648+
649+
.. code-block:: xml
650+
651+
<!-- app/config/security.xml -->
652+
<config>
653+
<!-- ... -->
654+
<encoder
655+
class="Symfony\Component\Security\Core\User\User"
656+
algorithm="argon2i"
657+
/>
658+
</config>
659+
660+
.. code-block:: php
661+
662+
// app/config/security.php
663+
use Symfony\Component\Security\Core\User\User;
664+
665+
$container->loadFromExtension('security', array(
666+
// ...
667+
'encoders' => array(
668+
User::class => array(
669+
'algorithm' => 'argon2i',
670+
),
671+
),
672+
));
673+
674+
A salt for each new password is generated automatically and need not be
675+
persisted. Since an encoded password contains the salt used to encode it,
676+
persisting the encoded password alone is enough.
677+
678+
.. note::
679+
680+
Argon2i encoded passwords are ``96`` characters long, but due to the hashing
681+
requirements saved in the resulting hash this may change in the future.
682+
683+
.. _reference-security-firewall-context:
624684

625685
Firewall Context
626686
----------------
@@ -749,3 +809,4 @@ To use HTTP-Digest authentication you need to provide a realm and a secret:
749809
750810
.. _`PBKDF2`: https://en.wikipedia.org/wiki/PBKDF2
751811
.. _`ircmaxell/password-compat`: https://packagist.org/packages/ircmaxell/password-compat
812+
.. _`libsodium`: https://pecl.php.net/package/libsodium

‎security.rst‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -457,8 +457,8 @@ C) Encoding the User's Password
457457
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
458458

459459
Whether your users are stored in ``security.yml``, in a database or somewhere
460-
else, you'll want to encode their passwords. The best algorithm to use is
461-
``bcrypt``:
460+
else, you'll want to encode their passwords. The most suitable algorithm to use
461+
is ``bcrypt``:
462462

463463
.. configuration-block::
464464

@@ -593,8 +593,8 @@ before inserting them into the database? Don't worry, see
593593

594594
Supported algorithms for this method depend on your PHP version, but
595595
include the algorithms returned by the PHP function :phpfunction:`hash_algos`
596-
as well as a few others (e.g. bcrypt). See the ``encoders`` key in the
597-
:doc:`Security Reference Section </reference/configuration/security>`
596+
as well as a few others (e.g. bcrypt and argon2i). See the ``encoders`` key
597+
in the :doc:`Security Reference Section </reference/configuration/security>`
598598
for examples.
599599

600600
It's also possible to use different hashing algorithms on a user-by-user

‎security/named_encoders.rst‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -101,6 +101,12 @@ named encoders:
101101
),
102102
));
103103
104+
.. note::
105+
106+
If you are running PHP 7.2+ or have the `libsodium`_ extension installed,
107+
then the recommended hashing algorithm to use is
108+
:ref:`Argon2i <reference-security-argon2i>`.
109+
104110
This creates an encoder named ``harsh``. In order for a ``User`` instance
105111
to use it, the class must implement
106112
:class:`Symfony\\Component\\Security\\Core\\Encoder\\EncoderAwareInterface`.
@@ -172,3 +178,5 @@ you must register a service for it in order to use it as a named encoder:
172178
173179
This creates an encoder named ``app_encoder`` from a service named
174180
``app.password_encoder_service``.
181+
182+
.. _`libsodium`: https://pecl.php.net/package/libsodium

0 commit comments

Comments
 (0)
0