bug #3600 [Security][Authentication] Fix instructions for creating pa…

…ssword encoders (bicpi)

This PR was merged into the 2.3 branch.

Discussion
----------

[Security][Authentication] Fix instructions for creating password encoders

| Q             | A
| ------------- | ---
| Doc fix?      | yes
| New docs?     | no
| Applies to    | 2.3+
| Fixed tickets | -

Please correct me if I am wrong, but it seems that the code has changed after #3003. There is no `BasePasswordEncoder::checkPasswordLength()` method. Same seems to apply to 2.4. Maybe the implementation was changed to make it bc?

Commits
-------

e95c1f5 [Security][Authentication] Fix instructions for creating custom password encoders

components/security/authentication.rst

@@ -198,10 +198,36 @@ own, it just needs to follow these rules:
 
 #. The class must implement :class:`Symfony\\Component\\Security\\Core\\Encoder\\PasswordEncoderInterface`;
 
-#. The first line in ``encodePassword`` and ``isPasswordValid`` must check
-   to make sure the password is not too long (e.g. 4096). This is for security
-   (see `CVE-2013-5750`_), and you can copy the `BasePasswordEncoder::checkPasswordLength`_
-   implementation from Symfony 2.4.
+#. The implementations of
+   :method:`Symfony\\Component\\Security\\Core\\Encoder\\PasswordEncoderInterface::encodePassword`
+   and
+   :method:`Symfony\\Component\\Security\\Core\\Encoder\\PasswordEncoderInterface::isPasswordValid`
+   must first of all make sure the password is not too long, i.e. the password length is no longer
+   than 4096 characters. This is for security reasons (see `CVE-2013-5750`_), and you can use the
+   :method:`Symfony\\Component\\Security\\Core\\Encoder\\BasePasswordEncoder::isPasswordTooLong`_
+   method for this check:
+
+       use Symfony\Component\Security\Core\Exception\BadCredentialsException;
+
+       class FoobarEncoder extends BasePasswordEncoder
+       {
+           public function encodePassword($raw, $salt)
+           {
+               if ($this->isPasswordTooLong($raw)) {
+                   throw new BadCredentialsException('Invalid password.');
+               }
+
+               // ...
+           }
+
+           public function isPasswordValid($encoded, $raw, $salt)
+           {
+               if ($this->isPasswordTooLong($raw)) {
+                   return false;
+               }
+
+               // ...
+       }
 
 Using Password Encoders
 ~~~~~~~~~~~~~~~~~~~~~~~