Skip to content

Navigation Menu

Sign in

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit be4f85c

Browse filesBrowse files
zanbaldwinzanbaldwin
committed
Argon2i Password Encoder
Add/modify sections for the Argon2i password encoder (symfony/symfony#21604).
1 parent 29900e9 commit be4f85c
Copy full SHA for be4f85c

File tree

5 files changed

+85
-6
lines changed
Filter options

5 files changed

+85
-6
lines changed

‎best_practices/security.rst

Copy file name to clipboardExpand all lines: best_practices/security.rst
+8Lines 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

Copy file name to clipboardExpand all lines: doctrine/registration_form.rst
+1-1Lines 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

Copy file name to clipboardExpand all lines: reference/configuration/security.rst
+64-1Lines changed: 64 additions & 1 deletion
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::
@@ -622,6 +626,64 @@ persisting the encoded password alone is enough.
622626

623627
.. _reference-security-firewall-context:
624628

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

@@ -749,3 +811,4 @@ To use HTTP-Digest authentication you need to provide a realm and a secret:
749811
750812
.. _`PBKDF2`: https://en.wikipedia.org/wiki/PBKDF2
751813
.. _`ircmaxell/password-compat`: https://packagist.org/packages/ircmaxell/password-compat
814+
.. _`libsodium`: https://pecl.php.net/package/libsodium

‎security.rst

Copy file name to clipboardExpand all lines: security.rst
+4-4Lines 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

Copy file name to clipboardExpand all lines: security/named_encoders.rst
+8Lines 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)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.