Skip to content

Commit 7e75b64

Browse files
weaverryanweaverryan
committed
minor #3533 Moving the new named algorithms into their own cookbook entry (weaverryan)
This PR was merged into the master branch. Discussion ---------- Moving the new named algorithms into their own cookbook entry Hi guys! This makes some changes to #3491: * moves the entry into a cookbook entry (to try to keep the security as short as possible) * tweaks inside the entry | Q | A | ------------- | --- | Doc fix? | no | New docs? | yes, PR symfony/symfony#10005 - but no, this is just a modification of #3491 | Applies to | 2.5+ | Fixed tickets | - Thanks! Commits ------- 34e69de [#3533] Lots of nice changes thanks to @xabbuh 2fbf17c [#3491] Moving the new named algorithms into their own cookbook entry and making some minor tweaks
2 parents 8ccfe85 + 34e69de commit 7e75b64

File tree

4 files changed

+128
-71
lines changed

4 files changed

+128
-71
lines changed

‎book/security.rst‎

Lines changed: 3 additions & 71 deletions
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‎

Lines changed: 1 addition & 0 deletions
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‎

Lines changed: 1 addition & 0 deletions
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‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
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+
<?xml version="1.0" encoding="UTF-8"?>
23+
<srv:container xmlns="http://symfony.com/schema/dic/security"
24+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
25+
xmlns:srv="http://symfony.com/schema/dic/services"
26+
xsi:schemaLocation="http://symfony.com/schema/dic/services
27+
http://symfony.com/schema/dic/services/services-1.0.xsd"
28+
>
29+
<config>
30+
<!-- ... -->
31+
<encoder class="Symfony\Component\Security\Core\User\User"
32+
algorithm="sha512"
33+
/>
34+
</config>
35+
</srv:container>
36+
37+
.. code-block:: php
38+
39+
// app/config/security.php
40+
$container->loadFromExtension('security', array(
41+
// ...
42+
'encoders' => array(
43+
'Symfony\Component\Security\Core\User\User' => array(
44+
'algorithm' => 'sha512',
45+
),
46+
),
47+
));
48+
49+
Another option is to use a "named" encoder and then select which encoder
50+
you want to use dynamically.
51+
52+
In the previous example, you've set the ``sha512`` algorithm for ``Acme\UserBundle\Entity\User``.
53+
This may be secure enough for a regular user, but what if you want your admins
54+
to have a stronger algorithm, for example ``bcrypt``. This can be done with
55+
named encoders:
56+
57+
.. configuration-block::
58+
59+
.. code-block:: yaml
60+
61+
# app/config/security.yml
62+
security:
63+
# ...
64+
encoders:
65+
harsh:
66+
algorithm: bcrypt
67+
cost: 15
68+
69+
.. code-block:: xml
70+
71+
<!-- app/config/security.xml -->
72+
<?xml version="1.0" encoding="UTF-8" ?>
73+
<srv:container xmlns="http://symfony.com/schema/dic/security"
74+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
75+
xmlns:srv="http://symfony.com/schema/dic/services"
76+
xsi:schemaLocation="http://symfony.com/schema/dic/services
77+
http://symfony.com/schema/dic/services/services-1.0.xsd"
78+
>
79+
80+
<config>
81+
<!-- ... -->
82+
<encoder class="harsh"
83+
algorithm="bcrypt"
84+
cost="15" />
85+
</config>
86+
</srv:container>
87+
88+
.. code-block:: php
89+
90+
// app/config/security.php
91+
$container->loadFromExtension('security', array(
92+
// ...
93+
'encoders' => array(
94+
'harsh' => array(
95+
'algorithm' => 'bcrypt',
96+
'cost' => '15'
97+
),
98+
),
99+
));
100+
101+
This creates an encoder named ``harsh``. In order for a ``User`` instance
102+
to use it, the class must implement
103+
:class:`Symfony\\Component\\Security\\Core\\Encoder\\EncoderAwareInterface`.
104+
The interface requires one method - ``getEncoderName`` - which should reutrn
105+
the name of the encoder to use::
106+
107+
// src/Acme/UserBundle/Entity/User.php
108+
namespace Acme\UserBundle\Entity;
109+
110+
use Symfony\Component\Security\Core\User\UserInterface;
111+
use Symfony\Component\Security\Core\Encoder\EncoderAwareInterface;
112+
113+
class User implements UserInterface, EncoderAwareInterface
114+
{
115+
public function getEncoderName()
116+
{
117+
if ($this->isAdmin()) {
118+
return 'harsh';
119+
}
120+
121+
return null; // use the default encoder
122+
}
123+
}

0 commit comments

Comments
 (0)