Fixed #31358 -- Increased salt entropy of password hashers.

Co-authored-by: Florian Apolloner <florian@apolloner.eu>

2 files changed, 23 insertions, 0 deletions

diff --git a/docs/releases/3.2.txt b/docs/releases/3.2.txt
index 3b1463be6f..307eb73d67 100644
--- a/docs/releases/3.2.txt
+++ b/docs/releases/3.2.txt
@@ -212,6 +212,9 @@ Minor features
   constrained environments. If this is the case, the existing hasher can be
   subclassed to override the defaults.
 
+* The default salt entropy for the Argon2, MD5, PBKDF2, SHA-1 password hashers
+  is increased from 71 to 128 bits.
+
 :mod:`django.contrib.contenttypes`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/topics/auth/passwords.txt b/docs/topics/auth/passwords.txt
index 00381ecdeb..28f22f048e 100644
--- a/docs/topics/auth/passwords.txt
+++ b/docs/topics/auth/passwords.txt
@@ -137,6 +137,26 @@ To use Bcrypt as your default storage algorithm, do the following:
 That's it -- now your Django install will use Bcrypt as the default storage
 algorithm.
 
+Increasing the salt entropy
+---------------------------
+
+.. versionadded:: 3.2
+
+Most password hashes include a salt along with their password hash in order to
+protect against rainbow table attacks. The salt itself is a random value which
+increases the size and thus the cost of the rainbow table and is currently set
+at 128 bits with the ``salt_entropy`` value in the ``BasePasswordHasher``. As
+computing and storage costs decrease this value should be raised. When
+implementing your own password hasher you are free to override this value in
+order to use a desired entropy level for your password hashes. ``salt_entropy``
+is measured in bits.
+
+.. admonition:: Implementation detail
+
+    Due to the method in which salt values are stored the ``salt_entropy``
+    value is effectively a minimum value. For instance a value of 128 would
+    provide a salt which would actually contain 131 bits of entropy.
+
 .. _increasing-password-algorithm-work-factor:
 
 Increasing the work factor