From c8eff0dbcb0936aac2748a7a896d08f34b54c50f Mon Sep 17 00:00:00 2001 From: Preston Holmes Date: Fri, 4 Jan 2013 17:42:25 -0800 Subject: [PATCH] Fixed #19562 -- cleaned up password storage docs --- docs/topics/auth/passwords.txt | 29 ++++++++++++++++------------- 1 file changed, 16 insertions(+), 13 deletions(-) diff --git a/docs/topics/auth/passwords.txt b/docs/topics/auth/passwords.txt index 76284ae72f..3d95b4b387 100644 --- a/docs/topics/auth/passwords.txt +++ b/docs/topics/auth/passwords.txt @@ -14,17 +14,19 @@ How Django stores passwords =========================== Django provides a flexible password storage system and uses PBKDF2 by default. -Older versions of Django used SHA1, and other algorithms couldn't be chosen. 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 @@ -36,13 +38,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::