8000 [#3356] Clarifying when you need a salt · symfony/symfony-docs@1eefb1b · GitHub
[go: up one dir, main page]

Skip to content

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Appearance settings

Commit 1eefb1b

Browse files
committed
[#3356] Clarifying when you need a salt
Also filling in other details related to using BCrypt
1 parent 0e6cc4d commit 1eefb1b

File tree

3 files changed

+39
-23
lines changed

3 files changed

+39
-23
lines changed

book/security.rst

Lines changed: 1 addition & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1349,19 +1349,7 @@ You can now calculate the hashed password either programmatically
13491349
(e.g. ``password_hash('ryanpass', PASSWORD_BCRYPT, array('cost' => 12));``)
13501350
or via some online tool.
13511351

1352-
.. caution::
1353-
1354-
If you're using PHP 5.4 or lower, you'll need to install the ``ircmaxell/password-compat``
1355-
library via Composer:
1356-
1357-
.. code-block:: json
1358-
1359-
{
1360-
"require": {
1361-
"...": "all the other dependencies...",
1362-
"ircmaxell/password-compat": "~1.0.3"
1363-
}
1364-
}
1352+
.. include:: /cookbook/security/_ircmaxwell_password-compat.rst.inc
13651353

13661354
Supported algorithms for this method depend on your PHP version. A full list
13671355
is available by calling the PHP function :phpfunction:`hash_algos`.
< 10000 /div>
Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
.. caution::
2+
3+
If you're using PHP 5.4 or lower, you'll need to install the ``ircmaxell/password-compat``
4+
library via Composer in order to be able to use the ``bcrypt`` encoder:
5+
6+
.. code-block:: json
7+
8+
{
9+
"require": {
10+
"...": "all the other dependencies...",
11+
"ircmaxell/password-compat": "~1.0.3"
12+
}
13+
}

cookbook/security/entity_provider.rst

Lines changed: 25 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,8 @@ focus on the most important methods that come from the
9595
public function __construct()
9696
{
9797
$this->isActive = true;
98+
// may not be needed, see section on salt below
99+
// $this->salt = md5(uniqid(null, true));
98100
}
99101
100102
/**
@@ -110,6 +112,8 @@ focus on the most important methods that come from the
110112
*/
111113
public function getSalt()
112114
{
115+
// you *may* need a real salt depending on your encoder
116+
// see section on salt below
113117
return null;
114118
}
115119
@@ -144,8 +148,9 @@ focus on the most important methods that come from the
144148
return serialize(array(
145149
$this->id,
146150
$this->username,
147-
$this->salt,
148151
$this->password,
152+
// see section on salt below
153+
// $this->salt,
149154
));
150155
}
151156
@@ -157,19 +162,13 @@ focus on the most important methods that come from the
157162
list (
158163
$this->id,
159164
$this->username,
160-
$this->salt,
161165
$this->password,
166+
// see section on salt below
167+
// $this->salt
162168
) = unserialize($serialized);
163169
}
164170
}
165171
166-
.. note::
167-
168-
If you choose to implement
169-
:class:`Symfony\\Component\\Security\\Core\\User\\EquatableInterface`,
170-
you determine yourself which properties need to be compared to distinguish
171-
your user objects.
172-
173172
.. tip::
174173

175174
:ref:`Generate the database table <book-doctrine-creating-the-database-tables-schema>`
@@ -186,7 +185,7 @@ interface forces the class to implement the five following methods:
186185

187186
* ``getRoles()``,
188187
* ``getPassword()``,
189-
* ``getPassword()``,
188+
* ``getSalt()``,
190189
* ``getUsername()``,
191190
* ``eraseCredentials()``
192191

@@ -213,6 +212,20 @@ The next part will focus on how to authenticate one of these users
213212
thanks to the Doctrine entity user provider and a couple of lines of
214213
configuration.
215214
215+
.. sidebar:: Do you need to use a Salt?
216+
217+
Yes. Hashing a password with a salt is a necessary step so that encoded
218+
passwords can't be decoded. However, some encoders - like Bcrypt - have
219+
a built-in salt mechanism. If you configure ``bcrypt`` as your encoder
220+
in ``security.yml`` (see the next section), then ``getSalt()`` should
221+
return ``null``, so that Bcrypt generates the salt itself.
222+
223+
However, if you use an encoder that does *not* have a built-in salting
224+
ability (e.g. ``sha512``), you *must* (from a security perspective) generate
225+
your own, random salt, store it on a ``salt`` property that is saved to
226+
the database, and return it from ``getSalt()``. Some of the code needed
227+
is commented out in the above example.
228+
216229
Authenticating Someone against a Database
217230
-----------------------------------------
218231
@@ -311,6 +324,8 @@ the database to be encoded using this encoder. For details on how to create
311324
a new User object with a properly encoded password, see the
312325
:ref:`book-security-encoding-user-password` section of the security chapter.
313326
327+
.. include:: /cookbook/security/_ircmaxwell_password-compat.rst.inc
328+
314329
The ``providers`` section defines an ``administrators`` user provider. A
315330
user provider is a "source" of where users are loaded during authentication.
316331
In this case, the ``entity`` keyword means that Symfony will use the Doctrine

0 commit comments

Comments
 (0)
0