Fixed #26033 -- Added Argon2 password hasher.

4 files changed, 79 insertions, 1 deletions

diff --git a/docs/internals/contributing/writing-code/unit-tests.txt b/docs/internals/contributing/writing-code/unit-tests.txt
index fb6fae1f72..37973261f4 100644
--- a/docs/internals/contributing/writing-code/unit-tests.txt
+++ b/docs/internals/contributing/writing-code/unit-tests.txt
@@ -137,6 +137,7 @@ Running all the tests
 If you want to run the full suite of tests, you'll need to install a number of
 dependencies:
 
+*  argon2-cffi_ 16.0.0+
 *  bcrypt_
 *  docutils_
 *  enum34_ (Python 2 only)
@@ -171,6 +172,7 @@ and install the Geospatial libraries</ref/contrib/gis/install/index>`.
 Each of these dependencies is optional. If you're missing any of them, the
 associated tests will be skipped.
 
+.. _argon2-cffi: https://pypi.python.org/pypi/argon2_cffi
 .. _bcrypt: https://pypi.python.org/pypi/bcrypt
 .. _docutils: https://pypi.python.org/pypi/docutils
 .. _enum34: https://pypi.python.org/pypi/enum34
diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt
index 9d94f53cfd..05276abae8 100644
--- a/docs/ref/settings.txt
+++ b/docs/ref/settings.txt
@@ -2684,6 +2684,7 @@ Default::
     [
         'django.contrib.auth.hashers.PBKDF2PasswordHasher',
         'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',
+        'django.contrib.auth.hashers.Argon2PasswordHasher',
         'django.contrib.auth.hashers.BCryptSHA256PasswordHasher',
         'django.contrib.auth.hashers.BCryptPasswordHasher',
     ]
@@ -2702,6 +2703,8 @@ Default::
     to strengthen the hashes in your database. If that's not feasible, add this
     setting to your project and add back any hashers that you need.
 
+    Also, the ``Argon2PasswordHasher`` was added.
+
 .. setting:: AUTH_PASSWORD_VALIDATORS
 
 ``AUTH_PASSWORD_VALIDATORS``
diff --git a/docs/releases/1.10.txt b/docs/releases/1.10.txt
index 47c964292f..2f617d3bea 100644
--- a/docs/releases/1.10.txt
+++ b/docs/releases/1.10.txt
@@ -70,6 +70,10 @@ Minor features
 :mod:`django.contrib.auth`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+* Added support for the :ref:`Argon2 password hash <argon2_usage>`. It's
+  recommended over PBKDF2, however, it's not the default as it requires a
+  third-party library.
+
 * The default iteration count for the PBKDF2 password hasher has been increased
   by 25%. This backwards compatible change will not affect users who have
   subclassed ``django.contrib.auth.hashers.PBKDF2PasswordHasher`` to change the
diff --git a/docs/topics/auth/passwords.txt b/docs/topics/auth/passwords.txt
index 47d6486dd9..578d917cf4 100644
--- a/docs/topics/auth/passwords.txt
+++ b/docs/topics/auth/passwords.txt
@@ -60,16 +60,53 @@ The default for :setting:`PASSWORD_HASHERS` is::
     PASSWORD_HASHERS = [
         'django.contrib.auth.hashers.PBKDF2PasswordHasher',
         'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',
+        'django.contrib.auth.hashers.Argon2PasswordHasher',
         'django.contrib.auth.hashers.BCryptSHA256PasswordHasher',
         'django.contrib.auth.hashers.BCryptPasswordHasher',
     ]
 
 This means that Django will use PBKDF2_ to store all passwords but will support
-checking passwords stored with PBKDF2SHA1 and bcrypt_.
+checking passwords stored with PBKDF2SHA1, argon2_, and bcrypt_.
 
 The next few sections describe a couple of common ways advanced users may want
 to modify this setting.
 
+.. _argon2_usage:
+
+Using Argon2 with Django
+------------------------
+
+.. versionadded:: 1.10
+
+Argon2_ is the winner of the 2015 `Password Hashing Competition`_, a community
+organized open competition to select a next generation hashing algorithm. It's
+designed not to be easier to compute on custom hardware than it is to compute
+on an ordinary CPU.
+
+Argon2_ is not the default for Django because it requires a third-party
+library. The Password Hashing Competition panel, however, recommends immediate
+use of Argon2 rather than the other algorithms supported by Django.
+
+To use Argon2 as your default storage algorithm, do the following:
+
+1. Install the `argon2-cffi library`_.  This can be done by running ``pip
+   install django[argon2]`` or by downloading the library and installing it
+   with ``python setup.py install``.
+
+2. Modify :setting:`PASSWORD_HASHERS` to list ``Argon2PasswordHasher`` first.
+   That is, in your settings file, you'd put::
+
+        PASSWORD_HASHERS = [
+            'django.contrib.auth.hashers.Argon2PasswordHasher',
+            'django.contrib.auth.hashers.PBKDF2PasswordHasher',
+            'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',
+            'django.contrib.auth.hashers.BCryptSHA256PasswordHasher',
+            'django.contrib.auth.hashers.BCryptPasswordHasher',
+        ]
+
+   Keep and/or add any entries in this list if you need Django to :ref:`upgrade
+   passwords <password-upgrades>`.
+
 .. _bcrypt_usage:
 
 Using ``bcrypt`` with Django
@@ -94,6 +131,7 @@ To use Bcrypt as your default storage algorithm, do the following:
             'django.contrib.auth.hashers.BCryptPasswordHasher',
             'django.contrib.auth.hashers.PBKDF2PasswordHasher',
             'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',
+            'django.contrib.auth.hashers.Argon2PasswordHasher',
         ]
 
    Keep and/or add any entries in this list if you need Django to :ref:`upgrade
@@ -132,6 +170,9 @@ algorithm.
 Increasing the work factor
 --------------------------
 
+PBKDF2 and bcrypt
+~~~~~~~~~~~~~~~~~
+
 The PBKDF2 and bcrypt algorithms use a number of iterations or rounds of
 hashing. This deliberately slows down attackers, making attacks against hashed
 passwords harder. However, as computing power increases, the number of
@@ -161,6 +202,7 @@ default PBKDF2 algorithm:
             'myproject.hashers.MyPBKDF2PasswordHasher',
             'django.contrib.auth.hashers.PBKDF2PasswordHasher',
             'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',
+            'django.contrib.auth.hashers.Argon2PasswordHasher',
             'django.contrib.auth.hashers.BCryptSHA256PasswordHasher',
             'django.contrib.auth.hashers.BCryptPasswordHasher',
         ]
@@ -168,6 +210,28 @@ default PBKDF2 algorithm:
 That's it -- now your Django install will use more iterations when it
 stores passwords using PBKDF2.
 
+Argon2
+~~~~~~
+
+Argon2 has three attributes that can be customized:
+
+#. ``time_cost`` controls the number of iterations within the hash.
+#. ``memory_cost`` controls the size of memory that must be used during the
+   computation of the hash.
+#. ``parallelism`` controls how many CPUs the computation of the hash can be
+   parallelized on.
+
+The default values of these attributes are probably fine for you. If you
+determine that the password hash is too fast or too slow, you can tweak it as
+follows:
+
+#. Choose ``parallelism`` to be the number of threads you can
+   spare computing the hash.
+#. Choose ``memory_cost`` to be the KiB of memory you can spare.
+#. Adjust ``time_cost`` and measure the time hashing a password takes.
+   Pick a ``time_cost`` that takes an acceptable time for you.
+   If ``time_cost`` set to 1 is unacceptably slow, lower ``memory_cost``.
+
 .. _password-upgrades:
 
 Password upgrading
@@ -286,6 +350,9 @@ Include any other hashers that your site uses in this list.
 .. _nist: http://csrc.nist.gov/publications/nistpubs/800-132/nist-sp800-132.pdf
 .. _bcrypt: https://en.wikipedia.org/wiki/Bcrypt
 .. _`bcrypt library`: https://pypi.python.org/pypi/bcrypt/
+.. _`argon2-cffi library`: https://pypi.python.org/pypi/argon2_cffi/
+.. _argon2: https://en.wikipedia.org/wiki/Argon2
+.. _`Password Hashing Competition`: https://password-hashing.net
 
 .. _auth-included-hashers:
 
@@ -297,6 +364,7 @@ The full list of hashers included in Django is::
     [
         'django.contrib.auth.hashers.PBKDF2PasswordHasher',
         'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',
+        'django.contrib.auth.hashers.Argon2PasswordHasher',
         'django.contrib.auth.hashers.BCryptSHA256PasswordHasher',
         'django.contrib.auth.hashers.BCryptPasswordHasher',
         'django.contrib.auth.hashers.SHA1PasswordHasher',
@@ -310,6 +378,7 @@ The corresponding algorithm names are:
 
 * ``pbkdf2_sha256``
 * ``pbkdf2_sha1``
+* ``argon2``
 * ``bcrypt_sha256``
 * ``bcrypt``
 * ``sha1``