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
  • reference/configuration
  • security
  • security.rst

    • 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"
    < A935 code>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