Clarified how contrib.auth picks a password hasher for verification.

1 files changed, 10 insertions, 6 deletions

diff --git a/docs/topics/auth/passwords.txt b/docs/topics/auth/passwords.txt
index 24ee2d5360..33a57a8be5 100644
--- a/docs/topics/auth/passwords.txt
+++ b/docs/topics/auth/passwords.txt
@@ -48,12 +48,16 @@ you're not sure, you probably don't.  If you do, please read on:
 
 Django chooses the algorithm to use by consulting the
 :setting:`PASSWORD_HASHERS` setting. This is a list of hashing algorithm
-classes that this Django installation supports. The first entry in this list
-(that is, ``settings.PASSWORD_HASHERS[0]``) will be used to store passwords,
-and all the other entries are valid hashers that can be used to check existing
-passwords.  This means that if you want to use a different algorithm, you'll
-need to modify :setting:`PASSWORD_HASHERS` to list your preferred algorithm
-first in the list.
+classes that this Django installation supports.
+
+For storing passwords, Django will use the first hasher in
+:setting:`PASSWORD_HASHERS`. To store new passwords with a different algorithm,
+put your preferred algorithm first in :setting:`PASSWORD_HASHERS`.
+
+For verifying passwords, Django will find the hasher in the list that matches
+the algorithm name in the stored password. If a stored password names an
+algorithm not found in :setting:`PASSWORD_HASHERS`, trying to verify it will
+raise ``ValueError``.
 
 The default for :setting:`PASSWORD_HASHERS` is::