8000 Fix #6103 by zsturgess · Pull Request #6104 · symfony/symfony-docs · GitHub
[go: up one dir, main page]
Skip to content

8000 Fix #6103 #6104

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

Fix #6103 #6104

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
8000
Diff view
55 changes: 26 additions & 29 deletions components/security/secure_tools.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 i 4592 n 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
0