Permalink
Browse files

Fixed #19562 -- cleaned up password storage docs

  • Loading branch information...
ptone committed Jan 5, 2013
1 parent b740da3 commit c8eff0dbcb0936aac2748a7a896d08f34b54c50f
Showing with 16 additions and 13 deletions.
  1. +16 −13 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
<algorithm>$<iterations>$<salt>$<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::

0 comments on commit c8eff0d

Please sign in to comment.