From 38085825b686405d623dd87c966685376bb99c3e Mon Sep 17 00:00:00 2001
From: Zac Sturgess <zac.sturgess@wearetwogether.com>
Date: Mon, 4 Jan 2016 16:39:28 +0000
Subject: [PATCH] Fix #6103

---
 components/security/secure_tools.rst | 55 +++++++++++++---------------
 1 file changed, 26 insertions(+), 29 deletions(-)

diff --git a/components/security/secure_tools.rst b/components/security/secure_tools.rst
index 4363f25fa36..378979f1cd9 100644
--- a/components/security/secure_tools.rst
+++ b/components/security/secure_tools.rst
@@ -1,47 +1,44 @@
-Securely Generating Random Numbers
-==================================
+Securely Generating Random Values 
+=================================
 
 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.
 
-Generating a Secure random Number
+Generating a Secure Random String
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-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::
+Whenever you need to generate a secure random string, you are highly
+encouraged to use the 
+:phpfunction:`random_bytes` function::
 
-    use Symfony\Component\Security\Core\Util\SecureRandom;
+    $random = random_bytes(10);
 
-    $generator = new SecureRandom();
-    $random = $generator->nextBytes(10);
+The function returns a random string, suitable for cryptographic use, of
+the number bytes passed as an argument (10 in the above example).
 
-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).
+.. tip::
 
-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::
+    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 encode or hash the value returned by ``random_bytes()`` (to do that, you
+    can use a simple ``base64_encode()`` PHP function).
 
-    use Symfony\Component\Security\Core\Util\SecureRandom;
+Generating a Secure Random Number
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    $generator = new SecureRandom('/some/path/to/store/the/seed.txt');
+If you need to generate a cryptographically secure random integer, you should
+use the
+:phpfunction:`random_int` function::
 
-    $random = $generator->nextBytes(10);
-    $hashedRandom = md5($random); // see tip below
+    $random = random_int(1, 10);
 
 .. note::
 
-    If you're using the Symfony Framework, you can get a secure random number
-    generator via the ``security.secure_random`` service.
+    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`_.
 
-.. tip::
-
-    The ``nextBytes()`` method 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
-    can use a simple ``md5()`` PHP function).
+.. _`Symfony Polyfill Component`: https://github.com/symfony/polyfill
+.. _`paragonie/random_compat package`: https://github.com/paragonie/random_compat