Rewrite Security documentation

Author: wouterj

_build/conf.py

@@ -119,19 +119,9 @@
 lexers['varnish3'] = CLexer()
 lexers['varnish4'] = CLexer()
 lexers['terminal'] = TerminalLexer()
+lexers['terminal-maker'] = TerminalLexer()
 lexers['env']  = BashLexer()
 
-config_block = {
-    'apache': 'Apache',
-    'markdown': 'Markdown',
-    'nginx': 'Nginx',
-    'rst': 'reStructuredText',
-    'varnish2': 'Varnish 2',
-    'varnish3': 'Varnish 3',
-    'varnish4': 'Varnish 4',
-    'env': '.env'
-}
-
 # don't enable Sphinx Domains
 primary_domain = None
 

_build/redirection_map

@@ -514,5 +514,5 @@
 /service_container/3.3-di-changes https://symfony.com/doc/3.4/service_container/3.3-di-changes.html
 /frontend/encore/shared-entry /frontend/encore/split-chunks
 /testing/functional_tests_assertions /testing#testing-application-assertions
-/security/named_encoders /security/named_hashers
 /security/experimental_authenticators /security/authenticator_manager
+/security/user_provider /security#security-user-providers

_images/security/anonymous_wdt.png

@@ -120,273 +120,6 @@ and to allow anonymous users to the login form page.
 
 This option is explained in detail in :doc:`/security/access_control`.
 
-.. _encoders:
-
-hashers
--------
-
-This option defines the algorithm used to *hash* the password of the users
-(which in previous Symfony versions was wrongly called *"password encoding"*).
-
-If your app defines more than one user class, each of them can define its own
-hashing algorithm. Also, each algorithm defines different config options:
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # config/packages/security.yaml
-        security:
-            # ...
-
-            password_hashers:
-                # auto hasher with default options
-                App\Entity\User: 'auto'
-
-                # auto hasher with custom options
-                App\Entity\User:
-                    algorithm: 'auto'
-                    cost:      15
-
-                # Sodium hasher with default options
-                App\Entity\User: 'sodium'
-
-                # Sodium hasher with custom options
-                App\Entity\User:
-                    algorithm:   'sodium'
-                    memory_cost:  16384 # Amount in KiB. (16384 = 16 MiB)
-                    time_cost:    2     # Number of iterations
-
-                # MessageDigestPasswordHasher hasher using SHA512 hashing with default options
-                App\Entity\User: 'sha512'
-
-    .. code-block:: xml
-
-        <!-- config/packages/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
-                https://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/security
-                https://symfony.com/schema/dic/security/security-1.0.xsd">
-
-            <config>
-                <!-- ... -->
-                <!-- auto hasher with default options -->
-                <security:password-hasher
-                    class="App\Entity\User"
-                    algorithm="auto"
-                />
-
-                <!-- auto hasher with custom options -->
-                <security:password-hasher
-                    class="App\Entity\User"
-                    algorithm="auto"
-                    cost="15"
-                />
-
-                <!-- Sodium hasher with default options -->
-                <security:password-hasher
-                    class="App\Entity\User"
-                    algorithm="sodium"
-                />
-
-                <!-- Sodium hasher with custom options -->
-                <!-- memory_cost: amount in KiB. (16384 = 16 MiB)
-                     time_cost: number of iterations -->
-                <security:password-hasher
-                    class="App\Entity\User"
-                    algorithm="sodium"
-                    memory_cost="16384"
-                    time_cost="2"
-                />
-
-                <!-- MessageDigestPasswordHasher hasher using SHA512 hashing with default options -->
-                <security:password-hasher
-                    class="App\Entity\User"
-                    algorithm="sha512"
-                />
-            </config>
-        </srv:container>
-
-    .. code-block:: php
-
-        // config/packages/security.php
-        use App\Entity\User;
-        use Symfony\Config\SecurityConfig;
-
-        return static function (SecurityConfig $security) {
-            // ...
-
-            // auto hasher with default options
-            $security->passwordHasher(User::class)
-                ->algorithm('auto');
-
-            // auto hasher with custom options
-            $security->passwordHasher(User::class)
-                ->algorithm('auto')
-                ->cost(15);
-
-            // Sodium hasher with default options
-            $security->passwordHasher(User::class)
-                ->algorithm('sodium');
-
-            // Sodium hasher with custom options
-            $security->passwordHasher(User::class)
-                ->algorithm('sodium')
-                ->memoryCost(16384) // Amount in KiB. (16384 = 16 MiB)
-                ->timeCost(2);      // Number of iterations
-
-            // MessageDigestPasswordHasher hasher using SHA512 hashing with default options
-            $security->passwordHasher(User::class)
-                ->algorithm('sha512');
-        };
-
-.. versionadded:: 5.3
-
-    The ``password_hashers`` option was introduced in Symfony 5.3. In previous
-    versions it was called ``encoders``.
-
-.. tip::
-
-    You can also create your own password hashers as services and you can even
-    select a different password hasher for each user instance. Read
-    :doc:`this article </security/named_hashers>` for more details.
-
-.. tip::
-
-    Hashing passwords is resource intensive and takes time in order to generate
-    secure password hashes. In tests however, secure hashes are not important, so
-    you can change the password hasher configuration in ``test`` environment to
-    run tests faster:
-
-    .. configuration-block::
-
-        .. code-block:: yaml
-
-            # config/packages/test/security.yaml
-            password_hashers:
-                # Use your user class name here
-                App\Entity\User:
-                    algorithm: auto # This should be the same value as in config/packages/security.yaml
-                    cost: 4 # Lowest possible value for bcrypt
-                    time_cost: 3 # Lowest possible value for argon
-                    memory_cost: 10 # Lowest possible value for argon
-
-        .. code-block:: xml
-
-            <!-- config/packages/test/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
-                    https://symfony.com/schema/dic/services/services-1.0.xsd">
-
-                <config>
-                    <!-- class: Use your user class name here -->
-                    <!-- algorithm: This should be the same value as in config/packages/security.yaml -->
-                    <!-- cost: Lowest possible value for bcrypt -->
-                    <!-- time_cost: Lowest possible value for argon -->
-                    <!-- memory_cost: Lowest possible value for argon -->
-                    <security:password-hasher
-                        class="App\Entity\User"
-                        algorithm="auto"
-                        cost="4"
-                        time_cost="3"
-                        memory_cost="10"
-                    />
-                </config>
-            </srv:container>
-
-        .. code-block:: php
-
-            // config/packages/test/security.php
-            use App\Entity\User;
-            use Symfony\Config\SecurityConfig;
-
-            return static function (SecurityConfig $security) {
-                // ...
-
-                // Use your user class name here
-                $security->passwordHasher(User::class)
-                    ->algorithm('auto') // This should be the same value as in config/packages/security.yaml
-                    ->cost(4) // Lowest possible value for bcrypt
-                    ->timeCost(2) // Lowest possible value for argon
-                    ->memoryCost(10) // Lowest possible value for argon
-                ;
-            };
-
-
-.. _reference-security-encoder-auto:
-.. _using-the-auto-password-encoder:
-
-Using the "auto" Password Hasher
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-It automatically selects the best available hasher. Starting from Symfony 5.3,
-it uses the Bcrypt hasher. If PHP or Symfony adds new password hashers in the
-future, it might select a different hasher.
-
-Because of this, the length of the hashed passwords may change in the future, so
-make sure to allocate enough space for them to be persisted (``varchar(255)``
-should be a good setting).
-
-.. _reference-security-encoder-bcrypt:
-
-Using the Bcrypt Password Hasher
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-It produces hashed passwords with the `bcrypt password hashing function`_.
-Hashed passwords are ``60`` characters long, so make sure to
-allocate enough space for them to be persisted. Also, passwords include the
-`cryptographic salt`_ inside them (it's generated automatically for each new
-password) so you don't have to deal with it.
-
-Its only configuration option is ``cost``, which is an integer in the range of
-``4-31`` (by default, ``13``). Each single increment of the cost **doubles the
-time** it takes to hash a password. It's designed this way so the password
-strength can be adapted to the future improvements in computation power.
-
-You can change the cost at any time — even if you already have some passwords
-hashed using a different cost. New passwords will be hashed using the new
-cost, while the already hashed ones will be validated using a cost that was
-used back when they were hashed.
-
-.. tip::
-
-    A simple technique to make tests much faster when using BCrypt is to set
-    the cost to ``4``, which is the minimum value allowed, in the ``test``
-    environment configuration.
-
-.. _reference-security-sodium:
-.. _using-the-argon2i-password-encoder:
-.. _using-the-sodium-password-encoder:
-
-Using the Sodium Password Hasher
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-It uses the `Argon2 key derivation function`_. Argon2 support was introduced
-in PHP 7.2 by bundeling the `libsodium`_ extension.
-
-The hashed passwords are ``96`` characters long, but due to the hashing
-requirements saved in the resulting hash this may change in the future, so make
-sure to allocate enough space for them to be persisted. Also, passwords include
-the `cryptographic salt`_ inside them (it's generated automatically for each new
-password) so you don't have to deal with it.
-
-.. _reference-security-pbkdf2:
-.. _using-the-pbkdf2-encoder:
-
-Using the PBKDF2 Hasher
-~~~~~~~~~~~~~~~~~~~~~~~
-
-Using the `PBKDF2`_ hasher is no longer recommended since PHP added support for
-Sodium and BCrypt. Legacy application still using it are encouraged to upgrade
-to those newer hashing algorithms.
-
 firewalls
 ---------