Updated Argon2i encoder by Sodium encoder

best_practices/security.rst

@@ -39,7 +39,7 @@ remain resistant to brute-force search attacks.
 
 .. note::
 
-    :ref:`Argon2i <reference-security-argon2i>` is the hashing algorithm as
+    :ref:`Sodium <reference-security-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.

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"
                 />
 
-                <!-- Argon2i encoder with default options -->
+                <!-- Sodium encoder with default options -->
                 <encoder
                     class="App\Entity\User"
-                    algorithm="argon2i"
+                    algorithm="sodium"
                 />
 
-                <!-- Argon2i encoder with custom options -->
+                <!-- Sodium encoder with custom options -->
                 <!-- memory_cost: amount in KiB. (16384 = 16 MiB)
                      time_cost: number of iterations
                      threads: number of parallel threads -->
                 <encoder
                     class="App\Entity\User"
-                    algorithm="argon2i"
+                    algorithm="sodium"
                     memory_cost="16384"
                     time_cost="2"
                     threads="4"
@@ -220,14 +220,14 @@ encoding algorithm. Also, each algorithm defines different config options:
                     'cost'      => 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 </security/named_encoders>` 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

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
 

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 <reference-security-argon2i>`.
+    :ref:`Sodium <reference-security-sodium>`.
 
 This creates an encoder named ``harsh``. In order for a ``User`` instance
 to use it, the class must implement