From 97cc58e0d10b7b28f37c8e2522165f487513ce1c Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 17 Apr 2019 09:20:29 +0200 Subject: [PATCH 1/2] Updated Argon2i encoder by Sodium encoder --- best_practices/security.rst | 2 +- reference/configuration/security.rst | 35 ++++++++++++++-------------- security.rst | 4 ++-- security/named_encoders.rst | 2 +- 4 files changed, 22 insertions(+), 21 deletions(-) diff --git a/best_practices/security.rst b/best_practices/security.rst index f746303d347..524b8866b72 100644 --- a/best_practices/security.rst +++ b/best_practices/security.rst @@ -39,7 +39,7 @@ remain resistant to brute-force search attacks. .. note:: - :ref:`Argon2i ` is the hashing algorithm as + :ref:`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. diff --git a/reference/configuration/security.rst b/reference/configuration/security.rst index 341a94495f2..6421691afdf 100644 --- a/reference/configuration/security.rst +++ b/reference/configuration/security.rst @@ -137,12 +137,12 @@ encoding algorithm. Also, each algorithm defines different config options: algorithm: 'bcrypt' cost: 15 - # Argon2i encoder with default options - App\Entity\User: 'argon2i' + # Sodium encoder with default options + App\Entity\User: 'sodium' - # Argon2i encoder with custom options + # Sodium encoder with custom options App\Entity\User: - algorithm: 'argon2i' + algorithm: 'sodium' memory_cost: 16384 # Amount in KiB. (16384 = 16 MiB) time_cost: 2 # Number of iterations threads: 4 # Number of parallel threads @@ -175,19 +175,19 @@ encoding algorithm. Also, each algorithm defines different config options: cost="15" /> - + - + 15, ], - // Argon2i encoder with default options + // Sodium encoder with default options User::class => [ - 'algorithm' => 'argon2i', + 'algorithm' => 'sodium', ], - // Argon2i encoder with custom options + // Sodium encoder with custom options User::class => [ - 'algorithm' => 'argon2i', + 'algorithm' => 'sodium', 'memory_cost' => 16384, // Amount in KiB. (16384 = 16 MiB) 'time_cost' => 2, // Number of iterations 'threads' => 4, // Number of parallel threads @@ -246,10 +246,11 @@ encoding algorithm. Also, each algorithm defines different config options: select a different password encoder for each user instance. Read :doc:`this article ` for more details. -.. _reference-security-argon2i: +.. _reference-security-sodium: +.. _using-the-argon2i-password-encoder: -Using the Argon2i Password Encoder -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Using the Sodium Password Encoder +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ It uses the `Argon2 key derivation function`_ and it's the encoder recommended by Symfony. Argon2 support was introduced in PHP 7.2, but if you use an earlier @@ -267,7 +268,7 @@ Using the BCrypt Password Encoder ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ It uses the `bcrypt password hashing function`_ and it's recommended to use it -when it's not possible to use Argon2i. The encoded passwords are ``60`` +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. 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. @@ -294,7 +295,7 @@ Using the PBKDF2 Encoder ~~~~~~~~~~~~~~~~~~~~~~~~ Using the `PBKDF2`_ encoder is no longer recommended since PHP added support for -Argon2i 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 diff --git a/security.rst b/security.rst index 0ca69ce403a..81369650310 100644 --- a/security.rst +++ b/security.rst @@ -124,8 +124,8 @@ command will pre-configure this for you: encoders: # use your user class name here App\Entity\User: - # bcrypt or argon2i are recommended - # argon2i is more secure, but requires PHP 7.2 or the Sodium extension + # bcrypt or sodium are recommended + # sodium is more secure, but requires PHP 7.2 or the Sodium extension algorithm: bcrypt cost: 12 diff --git a/security/named_encoders.rst b/security/named_encoders.rst index fbf57fe8dce..8f47feefabc 100644 --- a/security/named_encoders.rst +++ b/security/named_encoders.rst @@ -109,7 +109,7 @@ be done with named encoders: If you are running PHP 7.2+ or have the `libsodium`_ extension installed, then the recommended hashing algorithm to use is - :ref:`Argon2i `. + :ref:`Sodium `. This creates an encoder named ``harsh``. In order for a ``User`` instance to use it, the class must implement From 595174991e2fb93a6040ee48a3d5d560cb7c1e82 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 17 Apr 2019 09:23:21 +0200 Subject: [PATCH 2/2] Added the versionadded directives --- reference/configuration/security.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/reference/configuration/security.rst b/reference/configuration/security.rst index 6421691afdf..d25e415d83a 100644 --- a/reference/configuration/security.rst +++ b/reference/configuration/security.rst @@ -240,6 +240,11 @@ encoding algorithm. Also, each algorithm defines different config options: ], ]); +.. versionadded:: 4.3 + + The ``sodium`` algorithm was introduced in Symfony 4.3. In previous Symfony + versions it was called ``argon2i``. + .. tip:: You can also create your own password encoders as services and you can even @@ -252,6 +257,11 @@ encoding algorithm. Also, each algorithm defines different config options: Using the Sodium Password Encoder ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. versionadded:: 4.3 + + The ``SodiumPasswordEncoder`` was introduced in Symfony 4.3. In previous + Symfony versions it was called ``Argon2iPasswordEncoder``. + It uses the `Argon2 key derivation function`_ and it's the encoder recommended by Symfony. Argon2 support was introduced in PHP 7.2, but if you use an earlier PHP version, you can install the `libsodium`_ PHP extension.