Permalink
Browse files

minor #3533 Moving the new named algorithms into their own cookbook e…

…ntry (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
  • Loading branch information...
weaverryan committed Feb 4, 2014
2 parents 8ccfe85 + 34e69de commit 7e75b64a34659f48e07bb53b34264ed3fb827530
Showing with 128 additions and 71 deletions.
  1. +3 −71 book/security.rst
  2. +1 −0 cookbook/map.rst.inc
  3. +1 −0 cookbook/security/index.rst
  4. +123 −0 cookbook/security/named_encoders.rst
View
@@ -1434,78 +1434,10 @@ or via some online tool.
Supported algorithms for this method depend on your PHP version. A full list
is available by calling the PHP function :phpfunction:`hash_algos`.
Named encoders
..............
.. versionadded:: 2.5
Named encoders were introduced in Symfony 2.5
Another option is to set the encoder dynamically on an instance basis.
In the previous example, you've set the ``sha512`` algorithm for ``Acme\UserBundle\Entity\User``.
This may be secure enough for a regular user, but what if you want your admins to have
a stronger algorithm? Let's say ``bcrypt``. This can be done with named encoders:
.. configuration-block::
.. code-block:: yaml
# app/config/security.yml
security:
# ...
encoders:
harsh:
algorithm: bcrypt
cost: 15
.. code-block:: xml
<!-- app/config/security.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<srv:container xmlns="http://symfony.com/schema/dic/security"
xmlns:srv="http://symfony.com/schema/dic/services">
<config>
<!-- ... -->
<encoder class="harsh"
algorithm="bcrypt"
cost="15" />
</config>
</srv:container>
.. code-block:: php
// app/config/security.php
$container->loadFromExtension('security', array(
// ...
'encoders' => array(
'harsh' => array(
'algorithm' => 'bcrypt',
'cost' => '15'
),
),
));
Now you've created an encoder named ``harsh``. In order for a ``User`` instance to use it,
It must implement ``EncoderAwareInterface`` and have a method ``getEncoderName`` which returns the
name of the encoder to use::
// src/Acme/UserBundle/Entity/User.php
namespace Acme\UserBundle\Entity;
use Symfony\Component\Security\Core\User\UserInterface;
use Symfony\Component\Security\Core\Encoder\EncoderAwareInterface;
.. tip::
class User implements UserInterface, EncoderAwareInterface
{
public function getEncoderName()
{
if ($this->isAdmin()) {
return 'harsh';
}
return null; // use the default encoder
}
}
It's also possible to use different hashing algorithms on a user-by-user
basis. See :doc:`/cookbook/security/named-encoders` for more details.
Determining the Hashed Password
...............................
View
@@ -144,6 +144,7 @@
* :doc:`/cookbook/security/custom_authentication_provider`
* :doc:`/cookbook/security/target_path`
* :doc:`/cookbook/security/csrf_in_login_form`
* :doc:`/cookbook/security/named_encoders`
* **Serializer**
@@ -20,3 +20,4 @@ Security
custom_authentication_provider
target_path
csrf_in_login_form
named_encoders
@@ -0,0 +1,123 @@
.. index::
single: Security; Named Encoders
How to Choose the Password Encoder Algorithm Dynamically
========================================================
.. versionadded:: 2.5
Named encoders were introduced in Symfony 2.5.
Usually, the same password encoder is used for all users by configuring it
to apply to all instances of a specific class:
# app/config/security.yml
security:
# ...
encoders:
Symfony\Component\Security\Core\User\User: sha512
.. code-block:: xml
<!-- app/config/security.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<srv:container xmlns="http://symfony.com/schema/dic/security"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:srv="http://symfony.com/schema/dic/services"
xsi:schemaLocation="http://symfony.com/schema/dic/services
http://symfony.com/schema/dic/services/services-1.0.xsd"
>
<config>
<!-- ... -->
<encoder class="Symfony\Component\Security\Core\User\User"
algorithm="sha512"
/>
</config>
</srv:container>
.. code-block:: php
// app/config/security.php
$container->loadFromExtension('security', array(
// ...
'encoders' => array(
'Symfony\Component\Security\Core\User\User' => array(
'algorithm' => 'sha512',
),
),
));
Another option is to use a "named" encoder and then select which encoder
you want to use dynamically.
In the previous example, you've set the ``sha512`` algorithm for ``Acme\UserBundle\Entity\User``.
This may be secure enough for a regular user, but what if you want your admins
to have a stronger algorithm, for example ``bcrypt``. This can be done with
named encoders:
.. configuration-block::
.. code-block:: yaml
# app/config/security.yml
security:
# ...
encoders:
harsh:
algorithm: bcrypt
cost: 15
.. code-block:: xml
<!-- app/config/security.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<srv:container xmlns="http://symfony.com/schema/dic/security"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:srv="http://symfony.com/schema/dic/services"
xsi:schemaLocation="http://symfony.com/schema/dic/services
http://symfony.com/schema/dic/services/services-1.0.xsd"
>
<config>
<!-- ... -->
<encoder class="harsh"
algorithm="bcrypt"
cost="15" />
</config>
</srv:container>
.. code-block:: php
// app/config/security.php
$container->loadFromExtension('security', array(
// ...
'encoders' => array(
'harsh' => array(
'algorithm' => 'bcrypt',
'cost' => '15'
),
),
));
This creates an encoder named ``harsh``. In order for a ``User`` instance
to use it, the class must implement
:class:`Symfony\\Component\\Security\\Core\\Encoder\\EncoderAwareInterface`.
The interface requires one method - ``getEncoderName`` - which should reutrn
the name of the encoder to use::
// src/Acme/UserBundle/Entity/User.php
namespace Acme\UserBundle\Entity;
use Symfony\Component\Security\Core\User\UserInterface;
use Symfony\Component\Security\Core\Encoder\EncoderAwareInterface;
class User implements UserInterface, EncoderAwareInterface
{
public function getEncoderName()
{
if ($this->isAdmin()) {
return 'harsh';
}
return null; // use the default encoder
}
}

0 comments on commit 7e75b64

Please sign in to comment.