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..d25e415d83a 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 @@ -240,16 +240,27 @@ 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 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 Sodium Password Encoder +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.3 -Using the Argon2i Password Encoder -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + 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 @@ -267,7 +278,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 +305,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