diff --git a/components/security/secure_tools.rst b/components/security/secure_tools.rst index 4363f25fa36..f55a2063bbd 100644 --- a/components/security/secure_tools.rst +++ b/components/security/secure_tools.rst @@ -10,38 +10,27 @@ Generating a Secure random Number Whenever you need to generate a secure random number, you are highly encouraged to use the Symfony -:class:`Symfony\\Component\\Security\\Core\\Util\\SecureRandom` class:: +:phpfunction:`random_bytes` function:: - use Symfony\Component\Security\Core\Util\SecureRandom; + $random = random_bytes(10); - $generator = new SecureRandom(); - $random = $generator->nextBytes(10); - -The -:method:`Symfony\\Component\\Security\\Core\\Util\\SecureRandom::nextBytes` -method returns a random string composed of the number of characters passed as -an argument (10 in the above example). - -The SecureRandom class works better when OpenSSL is installed. But when it's -not available, it falls back to an internal algorithm, which needs a seed file -to work correctly. Just pass a file name to enable it:: - - use Symfony\Component\Security\Core\Util\SecureRandom; - - $generator = new SecureRandom('/some/path/to/store/the/seed.txt'); - - $random = $generator->nextBytes(10); - $hashedRandom = md5($random); // see tip below +The function returns a random string, suitable for cryptographic use, of +the number bytes passed as an argument (10 in the above example). .. note:: If you're using the Symfony Framework, you can get a secure random number generator via the ``security.secure_random`` service. +.. note:: + + PHP versions 7.0.0 and up provide the ``random_bytes()`` function natively, + on lower versions of PHP a polyfill is provided. + .. tip:: - The ``nextBytes()`` method returns a binary string which may contain the + The ``random_bytes()`` function returns a binary string which may contain the ``\0`` character. This can cause trouble in several common scenarios, such as storing this value in a database or including it as part of the URL. The - solution is to hash the value returned by ``nextBytes()`` (to do that, you + solution is to hash the value returned by ``random_bytes()`` (to do that, you can use a simple ``md5()`` PHP function).