Fixed #32275 -- Added scrypt password hasher.

Co-authored-by: Mariusz Felisiak <felisiak.mariusz@gmail.com>

2 files changed, 75 insertions, 0 deletions

diff --git a/docs/releases/4.0.txt b/docs/releases/4.0.txt
index 9162588d07..7275e1712d 100644
--- a/docs/releases/4.0.txt
+++ b/docs/releases/4.0.txt
@@ -58,6 +58,13 @@ For example::
 Functional unique constraints are added to models using the
 :attr:`Meta.constraints <django.db.models.Options.constraints>` option.
 
+``scrypt`` password hasher
+--------------------------
+
+The new :ref:`scrypt password hasher <scrypt-usage>` is more secure and
+recommended over PBKDF2. However, it's not the default as it requires OpenSSL
+1.1+ and more memory.
+
 Minor features
 --------------
 
diff --git a/docs/topics/auth/passwords.txt b/docs/topics/auth/passwords.txt
index 1d3d1653fa..c6383ed9a3 100644
--- a/docs/topics/auth/passwords.txt
+++ b/docs/topics/auth/passwords.txt
@@ -62,6 +62,7 @@ The default for :setting:`PASSWORD_HASHERS` is::
         'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',
         'django.contrib.auth.hashers.Argon2PasswordHasher',
         'django.contrib.auth.hashers.BCryptSHA256PasswordHasher',
+        'django.contrib.auth.hashers.ScryptPasswordHasher',
     ]
 
 This means that Django will use PBKDF2_ to store all passwords but will support
@@ -99,6 +100,7 @@ To use Argon2 as your default storage algorithm, do the following:
             'django.contrib.auth.hashers.PBKDF2PasswordHasher',
             'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',
             'django.contrib.auth.hashers.BCryptSHA256PasswordHasher',
+            'django.contrib.auth.hashers.ScryptPasswordHasher',
         ]
 
    Keep and/or add any entries in this list if you need Django to :ref:`upgrade
@@ -129,6 +131,7 @@ To use Bcrypt as your default storage algorithm, do the following:
             'django.contrib.auth.hashers.PBKDF2PasswordHasher',
             'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',
             'django.contrib.auth.hashers.Argon2PasswordHasher',
+            'django.contrib.auth.hashers.ScryptPasswordHasher',
         ]
 
    Keep and/or add any entries in this list if you need Django to :ref:`upgrade
@@ -137,6 +140,41 @@ 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.
 
+.. _scrypt-usage:
+
+Using ``scrypt`` with Django
+----------------------------
+
+.. versionadded:: 4.0
+
+scrypt_ is similar to PBKDF2 and bcrypt in utilizing a set number of iterations
+to slow down brute-force attacks. However, because PBKDF2 and bcrypt do not
+require a lot of memory, attackers with sufficient resources can launch
+large-scale parallel attacks in order to speed up the attacking process.
+scrypt_ is specifically designed to use more memory compared to other
+password-based key derivation functions in order to limit the amount of
+parallelism an attacker can use, see :rfc:`7914` for more details.
+
+To use scrypt_ as your default storage algorithm, do the following:
+
+#. Modify :setting:`PASSWORD_HASHERS` to list ``ScryptPasswordHasher`` first.
+   That is, in your settings file::
+
+        PASSWORD_HASHERS = [
+            'django.contrib.auth.hashers.ScryptPasswordHasher',
+            'django.contrib.auth.hashers.PBKDF2PasswordHasher',
+            'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',
+            'django.contrib.auth.hashers.Argon2PasswordHasher',
+            'django.contrib.auth.hashers.BCryptSHA256PasswordHasher',
+        ]
+
+   Keep and/or add any entries in this list if you need Django to :ref:`upgrade
+   passwords <password-upgrades>`.
+
+.. note::
+
+    ``scrypt`` requires OpenSSL 1.1+.
+
 Increasing the salt entropy
 ---------------------------
 
@@ -197,6 +235,7 @@ algorithm:
             'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',
             'django.contrib.auth.hashers.Argon2PasswordHasher',
             'django.contrib.auth.hashers.BCryptSHA256PasswordHasher',
+            'django.contrib.auth.hashers.ScryptPasswordHasher',
         ]
 
 That's it -- now your Django install will use more iterations when it
@@ -235,6 +274,32 @@ follows:
     ``memory_cost`` parameter differently from the value that Django uses. The
     conversion is given by ``memory_cost == 2 ** memory_cost_commandline``.
 
+``scrypt``
+~~~~~~~~~~
+
+.. versionadded:: 4.0
+
+scrypt_ has four attributes that can be customized:
+
+#. ``work_factor`` controls the number of iterations within the hash.
+#. ``block_size``
+#. ``parallelism`` controls how many threads will run in parallel.
+#. ``maxmem`` limits the maximum size of memory that can be used during the
+   computation of the hash. Defaults to ``0``, which means the default
+   limitation from the OpenSSL library.
+
+We've chosen reasonable defaults, but you may wish to tune it up or down,
+depending on your security needs and available processing power.
+
+.. admonition:: Estimating memory usage
+
+    The minimum memory requirement of scrypt_ is::
+
+        work_factor * 2 * block_size * 64
+
+    so you may need to tweak ``maxmem`` when changing the ``work_factor`` or
+    ``block_size`` values.
+
 .. _password-upgrades:
 
 Password upgrading
@@ -351,6 +416,7 @@ Include any other hashers that your site uses in this list.
 .. _`bcrypt library`: https://pypi.org/project/bcrypt/
 .. _`argon2-cffi library`: https://pypi.org/project/argon2-cffi/
 .. _argon2: https://en.wikipedia.org/wiki/Argon2
+.. _scrypt: https://en.wikipedia.org/wiki/Scrypt
 .. _`Password Hashing Competition`: https://www.password-hashing.net/
 
 .. _auth-included-hashers:
@@ -366,6 +432,7 @@ The full list of hashers included in Django is::
         'django.contrib.auth.hashers.Argon2PasswordHasher',
         'django.contrib.auth.hashers.BCryptSHA256PasswordHasher',
         'django.contrib.auth.hashers.BCryptPasswordHasher',
+        'django.contrib.auth.hashers.ScryptPasswordHasher',
         'django.contrib.auth.hashers.SHA1PasswordHasher',
         'django.contrib.auth.hashers.MD5PasswordHasher',
         'django.contrib.auth.hashers.UnsaltedSHA1PasswordHasher',
@@ -380,6 +447,7 @@ The corresponding algorithm names are:
 * ``argon2``
 * ``bcrypt_sha256``
 * ``bcrypt``
+* ``scrypt``
 * ``sha1``
 * ``md5``
 * ``unsalted_sha1``