From f02e1167d788280e33de3df68fa41e89cb083619 Mon Sep 17 00:00:00 2001 From: Preston Holmes Date: Fri, 4 Jan 2013 17:42:25 -0800 Subject: [PATCH] [1.5.x] Fixed #19562 -- cleaned up password storage docs Conflicts: docs/topics/auth/passwords.txt --- docs/topics/auth/passwords.txt | 28 ++++++++++++++++------------ 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/docs/topics/auth/passwords.txt b/docs/topics/auth/passwords.txt index b19c024a72..45fde9bbab 100644 --- a/docs/topics/auth/passwords.txt +++ b/docs/topics/auth/passwords.txt @@ -21,12 +21,15 @@ How Django stores passwords The :attr:`~django.contrib.auth.models.User.password` attribute of a :class:`~django.contrib.auth.models.User` object is a string in this format:: - algorithm$hash + $$$ -That's a storage algorithm, and hash, separated by the dollar-sign -character. The algorithm is one of a number of one way hashing or password -storage algorithms Django can use; see below. The hash is the result of the one- -way function. +Those are the components used for storing a User's password, separated by the +dollar-sign character and consist of: the hashing algorithm, the number of +algorithm iterations (work factor), the random salt, and the resulting password +hash. The algorithm is one of a number of one-way hashing or password storage +algorithms Django can use; see below. Iterations describe the number of times +the algorithm is run over the hash. Salt is the random seed used and the hash +is the result of the one-way function. By default, Django uses the PBKDF2_ algorithm with a SHA256 hash, a password stretching mechanism recommended by NIST_. This should be @@ -38,13 +41,14 @@ algorithm, or even use a custom algorithm to match your specific security situation. Again, most users shouldn't need to do this -- if you're not sure, you probably don't. If you do, please read on: -Django chooses the an algorithm 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. +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. The default for :setting:`PASSWORD_HASHERS` is::