Ticket #4151: docs.diff

docs/authentication.txt

@@ -198 +198 @@
 Passwords
 ---------
 
+The ``User.set_password()`` and ``User.check_password()`` functions handle
+the setting and checking of passwords behind the scenes.
+
 The ``password`` attribute of a ``User`` object is a string in this format::
 
     hashtype$salt$hash
 
 That's hashtype, salt and hash, separated by the dollar-sign character.
+Here is an example::
 
-Hashtype is either ``sha1`` (default), ``md5`` or ``crypt`` -- the algorithm
-used to perform a one-way hash of the password. Salt is a random string used
-to salt the raw password to create the hash. Note that the ``crypt`` method is
-only supported on platforms that have the standard Python ``crypt`` module
-available.
+    sha1$a1976$a36cc8cbf81742a8fb52e221aaeab48ed7f58ab4
 
-For example::
+Hashtype is the algorithm used to perform a one-way hash of the password.
+Possible values are ``sha1``, ``sha224``, ``sha256``, ``sha384``, ``md5`` or
+``crypt``.  Salt is a random string used to salt the raw password when
+creating the hash.  Note that some choices of hashtype may be unavailable,
+depending on your platform:
 
-    sha1$a1976$a36cc8cbf81742a8fb52e221aaeab48ed7f58ab4
+    * The ``crypt`` method is supported only on platforms that have the
+      standard Python ``crypt`` module available.
+    * The algorithms ``sha224``, ``sha256`` and ``sha384`` are supported
+      only on platforms that have the standard Python ``hashlib`` module
+      available (i.e., Python 2.5 or newer).  The hashtype defaults to
+      ``sha256`` on such platforms, but you can change this by defining
+      ``PASSWORD_HASH_ALGORITHM`` in your settings file.
+    * If ``hashlib`` isn't available (e.g., on Python 2.4), the hashtype
+      defaults to ``sha1`` and ``PASSWORD_HASH_ALGORITHM`` is ignored.
 
-The ``User.set_password()`` and ``User.check_password()`` functions handle
-the setting and checking of these values behind the scenes.
-
 Previous Django versions, such as 0.90, used simple MD5 hashes without password
 salts. For backwards compatibility, those are still supported; they'll be
 converted automatically to the new style the first time ``check_password()``