From 652c68ffeebd510a6f59e1b56b3e007d07683ad8 Mon Sep 17 00:00:00 2001 From: Adam Johnson Date: Thu, 13 Jan 2022 19:46:18 +0000 Subject: [PATCH] Clarified how contrib.auth picks a password hasher for verification. --- docs/topics/auth/passwords.txt | 16 ++++++++++------ 1 file 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::