8000 Argon2i Password Encoder · zanbaldwin/symfony-docs@26dc85c · GitHub
[go: up one dir, main page]
Skip to content

Commit 26dc85c

Browse files
zanbaldwinzanbaldwin
committed
Argon2i Password Encoder
Add/modify sections for the Argon2i password encoder (symfony/symfony#21604).
1 parent 7bb20ba commit 26dc85c

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

@@ -393,3 +400,4 @@ develop :doc:`your own user provider </security/custom_provider>` and
393400
.. _`ParamConverter`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html
394401
.. _`@Security annotation`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/security.html
395402
.. _`FOSUserBundle`: https://github.com/FriendsOfSymfony/FOSUserBundle
403+
.. _`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
@@ -80,6 +80,10 @@ Each part will be explained in the next section.
8080
algorithm: plaintext
8181
ignore_case: false
8282
83+
# Argon2i encoder
84+
Acme\DemoBundle\Entity\User6:
85+
algorithm: argon2i
86+
8387
providers: # Required
8488
# Examples:
8589
my_in_memory_provider:
@@ -609,10 +613,66 @@ persisting the encoded password alone is enough.
609613

610614
.. note::
611615

612-
All the encoded passwords are ``60`` characters long, so make sure to
616+
BCrypt encoded passwords are ``60`` characters long, so make sure to
613617
allocate enough space for them to be persisted.
614618

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

617677
Firewall Context
618678
----------------
@@ -737,3 +797,4 @@ To use HTTP-Digest authentication you need to provide a realm and a secret:
737797
738798
.. _`PBKDF2`: https://en.wikipedia.org/wiki/PBKDF2
739799
.. _`ircmaxell/password-compat`: https://packagist.org/packages/ircmaxell/password-compat
800+
.. _`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`.
@@ -124,3 +130,5 @@ the name of the encoder to use::
124130
return null; // use the default encoder
125131
}
126132
}
133+
134+
.. _`libsodium`: https://pecl.php.net/package/libsodium

0 commit comments

Comments
 (0)
0