Skip to content

Commit 782c649

Browse files
committed
[#1936] Moving new BCrypt details into the reference section and touching up a few things
1 parent b5056b3 commit 782c649

File tree

2 files changed

+76
-67
lines changed

2 files changed

+76
-67
lines changed

book/security.rst

Lines changed: 2 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -1336,72 +1336,8 @@ that the hashed password can't be decoded (i.e. you can't determine the password
13361336
from the hashed password).
13371337

13381338
.. versionadded:: 2.2
1339-
As of Symfony 2.2 you can also use the PBKDF2 password encoder.
1340-
1341-
Using the BCrypt Password Encoder
1342-
.................................
1343-
1344-
.. versionadded:: 2.2
1345-
The BCrypt password encoder was added in Symfony 2.2.
1346-
1347-
.. configuration-block::
1348-
1349-
.. code-block:: yaml
1350-
1351-
# app/config/security.yml
1352-
security:
1353-
# ...
1354-
encoders:
1355-
Symfony\Component\Security\Core\User\User:
1356-
algorithm: bcrypt
1357-
cost: 15
1358-
1359-
.. code-block:: xml
1360-
1361-
<!-- app/config/security.xml -->
1362-
<config>
1363-
<!-- ... -->
1364-
<encoder
1365-
class="Symfony\Component\Security\Core\User\User"
1366-
algorithm="bcrypt"
1367-
cost="15"
1368-
/>
1369-
</config>
1370-
1371-
.. code-block:: php
1372-
1373-
// app/config/security.php
1374-
$container->loadFromExtension('security', array(
1375-
// ...
1376-
'encoders' => array(
1377-
'Symfony\Component\Security\Core\User\User' => array(
1378-
'algorithm' => 'bcrypt',
1379-
'cost' => 15,
1380-
),
1381-
),
1382-
));
1383-
1384-
``cost`` can be in the range of ``4-31`` and determines how long a password
1385-
will be encoded. Each increment of ``cost`` *doubles* the time it takes to
1386-
encode a password.
1387-
1388-
If you don't provide the ``cost`` option, the default cost of ``13`` is used.
1389-
1390-
.. note::
1391-
1392-
You can change the cost at any time — even if you already have some
1393-
passwords encoded using a different cost. New passwords will be encoded
1394-
using the new cost, while the already encoded ones will be validated
1395-
using a cost that was used back when they were encoded.
1396-
1397-
A salt for each new password is generated automatically and need not be
1398-
persisted. Since an encoded password contains the salt used to encode it,
1399-
persisting the encoded password alone is enough.
1400-
1401-
.. note::
1402-
1403-
All the encoded passwords are ``60`` characters long, so make sure to
1404-
allocate enough space for them to be persisted.
1339+
As of Symfony 2.2 you can also use the :ref:`PBKDF2<reference-security-pbkdf2>`
1340+
and :ref:`BCrypt<reference-security-bcrypt>` password encoders.
14051341

14061342
Determining the Hashed Password
14071343
...............................

reference/configuration/security.rst

Lines changed: 74 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -270,20 +270,92 @@ Redirecting after Login
270270
* ``target_path_parameter`` (type: ``string``, default: ``_target_path``)
271271
* ``use_referer`` (type: ``Boolean``, default: ``false``)
272272

273+
.. _reference-security-pbkdf2:
274+
273275
Using the PBKDF2 encoder: security and speed
274276
--------------------------------------------
275277

278+
.. versionadded:: 2.2
279+
The PBKDF2 password encoder was added in Symfony 2.2.
280+
276281
The `PBKDF2`_ encoder provides a high level of Cryptographic security, as
277282
recommended by the National Institute of Standards and Technology (NIST).
278283

284+
You can see an example of the ``pbkdf2`` encoder in the YAML block on this page.
285+
279286
But using PBKDF2 also warrants a warning: using it (with a high number
280287
of iterations) slows down the process. Thus, PBKDF2 should be used with
281288
caution and care.
282289

283290
A good configuration lies around at least 1000 iterations and sha512
284291
for the hash algorithm.
285292

286-
.. _`PBKDF2`: http://en.wikipedia.org/wiki/PBKDF2
293+
.. _reference-security-bcrypt:
294+
295+
Using the BCrypt Password Encoder
296+
---------------------------------
297+
298+
.. versionadded:: 2.2
299+
The BCrypt password encoder was added in Symfony 2.2.
300+
301+
.. configuration-block::
302+
303+
.. code-block:: yaml
304+
305+
# app/config/security.yml
306+
security:
307+
# ...
308+
encoders:
309+
Symfony\Component\Security\Core\User\User:
310+
algorithm: bcrypt
311+
cost: 15
312+
313+
.. code-block:: xml
314+
315+
<!-- app/config/security.xml -->
316+
<config>
317+
<!-- ... -->
318+
<encoder
319+
class="Symfony\Component\Security\Core\User\User"
320+
algorithm="bcrypt"
321+
cost="15"
322+
/>
323+
</config>
324+
325+
.. code-block:: php
326+
327+
// app/config/security.php
328+
$container->loadFromExtension('security', array(
329+
// ...
330+
'encoders' => array(
331+
'Symfony\Component\Security\Core\User\User' => array(
332+
'algorithm' => 'bcrypt',
333+
'cost' => 15,
334+
),
335+
),
336+
));
337+
338+
The ``cost`` can be in the range of ``4-31`` and determines how long a password
339+
will be encoded. Each increment of ``cost`` *doubles* the time it takes to
340+
encode a password.
341+
342+
If you don't provide the ``cost`` option, the default cost of ``13`` is used.
343+
344+
.. note::
345+
346+
You can change the cost at any time — even if you already have some
347+
passwords encoded using a different cost. New passwords will be encoded
348+
using the new cost, while the already encoded ones will be validated
349+
using a cost that was used back when they were encoded.
350+
351+
A salt for each new password is generated automatically and need not be
352+
persisted. Since an encoded password contains the salt used to encode it,
353+
persisting the encoded password alone is enough.
354+
355+
.. note::
356+
357+
All the encoded passwords are ``60`` characters long, so make sure to
358+
allocate enough space for them to be persisted.
287359

288360
HTTP-Digest Authentication
289361
--------------------------
@@ -325,3 +397,4 @@ To use HTTP-Digest authentication you need to provide a realm and a key:
325397
),
326398
));
327399
400+
.. _`PBKDF2`: http://en.wikipedia.org/wiki/PBKDF2

0 commit comments

Comments
 (0)