|
1 | | -Securely Generating Random Numbers |
2 | | -================================== |
| 1 | +Securely Generating Random Values |
| 2 | +================================= |
3 | 3 |
|
4 | 4 | The Symfony Security component comes with a collection of nice utilities |
5 | 5 | related to security. These utilities are used by Symfony, but you should |
6 | 6 | also use them if you want to solve the problem they address. |
7 | 7 |
|
8 | | -Generating a Secure random Number |
| 8 | +Generating a Secure Random String |
9 | 9 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
10 | 10 |
|
11 | | -Whenever you need to generate a secure random number, you are highly |
12 | | -encouraged to use the Symfony |
13 | | -:class:`Symfony\\Component\\Security\\Core\\Util\\SecureRandom` class:: |
| 11 | +Whenever you need to generate a secure random string, you are highly |
| 12 | +encouraged to use the |
| 13 | +:phpfunction:`random_bytes` function:: |
14 | 14 |
|
15 | | - use Symfony\Component\Security\Core\Util\SecureRandom; |
| 15 | + $random = random_bytes(10); |
16 | 16 |
|
17 | | - $generator = new SecureRandom(); |
18 | | - $random = $generator->nextBytes(10); |
| 17 | +The function returns a random string, suitable for cryptographic use, of |
| 18 | +the number bytes passed as an argument (10 in the above example). |
19 | 19 |
|
20 | | -The |
21 | | -:method:`Symfony\\Component\\Security\\Core\\Util\\SecureRandom::nextBytes` |
22 | | -method returns a random string composed of the number of characters passed as |
23 | | -an argument (10 in the above example). |
| 20 | +.. tip:: |
24 | 21 |
|
25 | | -The SecureRandom class works better when OpenSSL is installed. But when it's |
26 | | -not available, it falls back to an internal algorithm, which needs a seed file |
27 | | -to work correctly. Just pass a file name to enable it:: |
| 22 | + The ``random_bytes()`` function returns a binary string which may contain the |
| 23 | + ``\0`` character. This can cause trouble in several common scenarios, such |
| 24 | + as storing this value in a database or including it as part of the URL. The |
| 25 | + solution is to hash the value returned by ``random_bytes()`` (to do that, you |
| 26 | + can use a simple ``md5()`` PHP function). |
28 | 27 |
|
29 | | - use Symfony\Component\Security\Core\Util\SecureRandom; |
| 28 | +Generating a Secure Random Number |
| 29 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
30 | 30 |
|
31 | | - $generator = new SecureRandom('/some/path/to/store/the/seed.txt'); |
| 31 | +If you need to generate a cryptographically secure random integer, you should |
| 32 | +use the |
| 33 | +:phpfunction:`random_int` function:: |
32 | 34 |
|
33 | | - $random = $generator->nextBytes(10); |
34 | | - $hashedRandom = md5($random); // see tip below |
| 35 | + $random = random_int(1, 10); |
35 | 36 |
|
36 | 37 | .. note:: |
37 | 38 |
|
38 | | - If you're using the Symfony Framework, you can get a secure random number |
39 | | - generator via the ``security.secure_random`` service. |
| 39 | + PHP 7 and up provide the ``random_bytes()`` and ``random_int()`` functions natively, |
| 40 | + for older versions of PHP a polyfill is provided by the `Symfony Polyfill Component`_ |
| 41 | + and the `paragonie/random_compat package`_. |
40 | 42 |
|
41 | | -.. tip:: |
| 43 | +.. versionadded:: 2.8 |
42 | 44 |
|
43 | | - The ``nextBytes()`` method returns a binary string which may contain the |
44 | | - ``\0`` character. This can cause trouble in several common scenarios, such |
45 | | - as storing this value in a database or including it as part of the URL. The |
46 | | - solution is to hash the value returned by ``nextBytes()`` (to do that, you |
47 | | - can use a simple ``md5()`` PHP function). |
| 45 | + The `paragonie/random_compat package`_ was added as a dependancy of the Symfony Security Component in 2.8. You will need to manually require the package as a dependancy of your project in versions of Symfony prior to 2.8. |
| 46 | + |
| 47 | +.. _`Symfony Polyfill Component`: https://github.com/symfony/polyfill |
| 48 | +.. _`paragonie/random_compat package`: https://github.com/paragonie/random_compat |
0 commit comments