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)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy