feature symfony#6231 Use hash_equals instead of StringUtils::equals (WouterJ)

This PR was merged into the 2.3 branch.

Discussion
----------

Use hash_equals instead of StringUtils::equals

| Q | A
| --- | ---
| doc fix? | yes
| new docs? | yes
| applies to | 2.3+
| Fixed tickets | -

We've merged symfony#6104 in the 2.3 branch, so I think we should use the `hash_equals` function the 2.3 docs as well. Now, this article isn't related to the Security component at all and it might be a good start for the Polyfill component.

Commits
-------

9f7f1dd Use hash_equals instead of StringUtils::equals

Author: xabbuh

components/security/secure_tools.rst

@@ -5,21 +5,25 @@ The Symfony Security component comes with a collection of nice utilities
 related to security. These utilities are used by Symfony, but you should
 also use them if you want to solve the problem they address.
 
+.. note::
+
+    The functions described in this article were introduced in PHP 5.6 or 7.
+    For older PHP versions, a polyfill is provided by the
+    `Symfony Polyfill Component`_.
+
 Comparing Strings
 ~~~~~~~~~~~~~~~~~
 
 The time it takes to compare two strings depends on their differences. This
 can be used by an attacker when the two strings represent a password for
 instance; it is known as a `Timing attack`_.
 
-Internally, when comparing two passwords, Symfony uses a constant-time
-algorithm; you can use the same strategy in your own code thanks to the
-:class:`Symfony\\Component\\Security\\Core\\Util\\StringUtils` class::
-
-    use Symfony\Component\Security\Core\Util\StringUtils;
+When comparing two passwords, you should use the :phpfunction:`hash_equals`
+function::
 
-    // is some known string (e.g. password) equal to some user input?
-    $bool = StringUtils::equals($knownString, $userInput);
+    if (hash_equals($knownString, $userInput)) {
+        // ...
+    }
 
 Generating a Secure Random String
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -49,12 +53,5 @@ use the :phpfunction:`random_int` function::
 
     $random = random_int(1, 10);
 
-.. note::
-
-    PHP 7 and up provide the ``random_bytes()`` and ``random_int()`` functions
-    natively, for older versions of PHP a polyfill is provided by the
-    `Symfony Polyfill Component`_ and the `paragonie/random_compat package`_.
-
 .. _`Timing attack`: https://en.wikipedia.org/wiki/Timing_attack
 .. _`Symfony Polyfill Component`: https://github.com/symfony/polyfill
-.. _`paragonie/random_compat package`: https://github.com/paragonie/random_compat