Skip to content

Commit 2fbf17c

Browse files
weaverryanweaverryan
committed
[#3491] Moving the new named algorithms into their own cookbook entry and making some minor tweaks
1 parent 8ccfe85 commit 2fbf17c

File tree

4 files changed

+116
-71
lines changed

4 files changed

+116
-71
lines changed

‎book/security.rst

+3-71
Original file line numberDiff line numberDiff line change
@@ -1434,78 +1434,10 @@ or via some online tool.
14341434
Supported algorithms for this method depend on your PHP version. A full list
14351435
is available by calling the PHP function :phpfunction:`hash_algos`.
14361436

1437-
Named encoders
1438-
..............
1439-
1440-
.. versionadded:: 2.5
1441-
Named encoders were introduced in Symfony 2.5
1442-
1443-
Another option is to set the encoder dynamically on an instance basis.
1444-
In the previous example, you've set the ``sha512`` algorithm for ``Acme\UserBundle\Entity\User``.
1445-
This may be secure enough for a regular user, but what if you want your admins to have
1446-
a stronger algorithm? Let's say ``bcrypt``. This can be done with named encoders:
1447-
1448-
.. configuration-block::
1449-
1450-
.. code-block:: yaml
1451-
1452-
# app/config/security.yml
1453-
security:
1454-
# ...
1455-
encoders:
1456-
harsh:
1457-
algorithm: bcrypt
1458-
cost: 15
1459-
1460-
.. code-block:: xml
1461-
1462-
<!-- app/config/security.xml -->
1463-
<?xml version="1.0" encoding="UTF-8" ?>
1464-
<srv:container xmlns="http://symfony.com/schema/dic/security"
1465-
xmlns:srv="http://symfony.com/schema/dic/services">
1466-
1467-
<config>
1468-
<!-- ... -->
1469-
<encoder class="harsh"
1470-
algorithm="bcrypt"
1471-
cost="15" />
1472-
</config>
1473-
</srv:container>
1474-
1475-
.. code-block:: php
1476-
1477-
// app/config/security.php
1478-
$container->loadFromExtension('security', array(
1479-
// ...
1480-
'encoders' => array(
1481-
'harsh' => array(
1482-
'algorithm' => 'bcrypt',
1483-
'cost' => '15'
1484-
),
1485-
),
1486-
));
1487-
1488-
Now you've created an encoder named ``harsh``. In order for a ``User`` instance to use it,
1489-
It must implement ``EncoderAwareInterface`` and have a method ``getEncoderName`` which returns the
1490-
name of the encoder to use::
1491-
1492-
// src/Acme/UserBundle/Entity/User.php
1493-
namespace Acme\UserBundle\Entity;
1494-
1495-
use Symfony\Component\Security\Core\User\UserInterface;
1496-
use Symfony\Component\Security\Core\Encoder\EncoderAwareInterface;
1437+
.. tip::
14971438

1498-
class User implements UserInterface, EncoderAwareInterface
1499-
{
1500-
public function getEncoderName()
1501-
{
1502-
if ($this->isAdmin()) {
1503-
return 'harsh';
1504-
}
1505-
1506-
return null; // use the default encoder
1507-
}
1508-
}
1439+
It's also possible to use different hashing algorithms on a user-by-user
1440+
basis. See :doc:`/cookbook/security/named-encoders` for more details.
15091441

15101442
Determining the Hashed Password
15111443
...............................

‎cookbook/map.rst.inc

+1
Original file line numberDiff line numberDiff line change
@@ -144,6 +144,7 @@
144144
* :doc:`/cookbook/security/custom_authentication_provider`
145145
* :doc:`/cookbook/security/target_path`
146146
* :doc:`/cookbook/security/csrf_in_login_form`
147+
* :doc:`/cookbook/security/named_encoders`
147148

148149
* **Serializer**
149150

‎cookbook/security/index.rst

+1
Original file line numberDiff line numberDiff line change
@@ -20,3 +20,4 @@ Security
2020
custom_authentication_provider
2121
target_path
2222
csrf_in_login_form
23+
named_encoders

‎cookbook/security/named_encoders.rst

+111
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
.. index::
2+
single: Security; Named Encoders
3+
4+
How to Choose the Password Encoder Algorithm Dynamically
5+
========================================================
6+
7+
.. versionadded:: 2.5
8+
Named encoders were introduced in Symfony 2.5
9+
10+
Usually, the same password encoder is used for all users by configuring it
11+
to apply to all instances of a specific class:
12+
13+
# app/config/security.yml
14+
security:
15+
# ...
16+
encoders:
17+
Symfony\Component\Security\Core\User\User: sha512
18+
19+
.. code-block:: xml
20+
21+
<!-- app/config/security.xml -->
22+
<config>
23+
<!-- ... -->
24+
<encoder class="Symfony\Component\Security\Core\User\User"
25+
algorithm="sha512"
26+
/>
27+
</config>
28+
29+
.. code-block:: php
30+
31+
// app/config/security.php
32+
$container->loadFromExtension('security', array(
33+
// ...
34+
'encoders' => array(
35+
'Symfony\Component\Security\Core\User\User' => array(
36+
'algorithm' => 'sha512',
37+
),
38+
),
39+
));
40+
41+
Another option is to use a "named" encoder, and then select which encoder
42+
you want to use dynamically.
43+
44+
In the previous example, you've set the ``sha512`` algorithm for ``Acme\UserBundle\Entity\User``.
45+
This may be secure enough for a regular user, but what if you want your admins
46+
to have a stronger algorithm, for example ``bcrypt``. This can be done with
47+
named encoders:
48+
49+
.. configuration-block::
50+
51+
.. code-block:: yaml
52+
53+
# app/config/security.yml
54+
security:
55+
# ...
56+
encoders:
57+
harsh:
58+
algorithm: bcrypt
59+
cost: 15
60+
61+
.. code-block:: xml
62+
63+
<!-- app/config/security.xml -->
64+
<?xml version="1.0" encoding="UTF-8" ?>
65+
<srv:container xmlns="http://symfony.com/schema/dic/security"
66+
xmlns:srv="http://symfony.com/schema/dic/services">
67+
68+
<config>
69+
<!-- ... -->
70+
<encoder class="harsh"
71+
algorithm="bcrypt"
72+
cost="15" />
73+
</config>
74+
</srv:container>
75+
76+
.. code-block:: php
77+
78+
// app/config/security.php
79+
$container->loadFromExtension('security', array(
80+
// ...
81+
'encoders' => array(
82+
'harsh' => array(
83+
'algorithm' => 'bcrypt',
84+
'cost' => '15'
85+
),
86+
),
87+
));
88+
89+
This creates an encoder named ``harsh``. In order for a ``User`` instance
90+
to use it, the class must implement
91+
:class:`Symfony\\Component\\Security\\Core\\Encoder\\EncoderAwareInterface`.
92+
The interface requires one method - ``getEncoderName`` - which should reutrn
93+
the name of the encoder to use::
94+
95+
// src/Acme/UserBundle/Entity/User.php
96+
namespace Acme\UserBundle\Entity;
97+
98+
use Symfony\Component\Security\Core\User\UserInterface;
99+
use Symfony\Component\Security\Core\Encoder\EncoderAwareInterface;
100+
101+
class User implements UserInterface, EncoderAwareInterface
102+
{
103+
public function getEncoderName()
104+
{
105+
if ($this->isAdmin()) {
106+
return 'harsh';
107+
}
108+
109+
return null; // use the default encoder
110+
}
111+
}

0 commit comments

Comments
 (0)