diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/releases/1.6.txt | 3 | ||||
| -rw-r--r-- | docs/topics/auth/passwords.txt | 25 |
2 files changed, 25 insertions, 3 deletions
diff --git a/docs/releases/1.6.txt b/docs/releases/1.6.txt index 236be7b1d3..372dde8ff9 100644 --- a/docs/releases/1.6.txt +++ b/docs/releases/1.6.txt @@ -181,6 +181,9 @@ Minor features and the undocumented limit of the higher of 1000 or ``max_num`` forms was changed so it is always 1000 more than ``max_num``. +* Added ``BCryptSHA256PasswordHasher`` to resolve the password truncation issue + with bcrypt. + Backwards incompatible changes in 1.6 ===================================== diff --git a/docs/topics/auth/passwords.txt b/docs/topics/auth/passwords.txt index d9b7e24efc..ae63771d6f 100644 --- a/docs/topics/auth/passwords.txt +++ b/docs/topics/auth/passwords.txt @@ -52,6 +52,7 @@ The default for :setting:`PASSWORD_HASHERS` is:: PASSWORD_HASHERS = ( 'django.contrib.auth.hashers.PBKDF2PasswordHasher', 'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher', + 'django.contrib.auth.hashers.BCryptSHA256PasswordHasher', 'django.contrib.auth.hashers.BCryptPasswordHasher', 'django.contrib.auth.hashers.SHA1PasswordHasher', 'django.contrib.auth.hashers.MD5PasswordHasher', @@ -79,10 +80,11 @@ To use Bcrypt as your default storage algorithm, do the following: py-bcrypt``, or downloading the library and installing it with ``python setup.py install``). -2. Modify :setting:`PASSWORD_HASHERS` to list ``BCryptPasswordHasher`` +2. Modify :setting:`PASSWORD_HASHERS` to list ``BCryptSHA256PasswordHasher`` first. That is, in your settings file, you'd put:: PASSWORD_HASHERS = ( + 'django.contrib.auth.hashers.BCryptSHA256PasswordHasher', 'django.contrib.auth.hashers.BCryptPasswordHasher', 'django.contrib.auth.hashers.PBKDF2PasswordHasher', 'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher', @@ -97,6 +99,22 @@ 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. +.. admonition:: Password truncation with BCryptPasswordHasher + + The designers of bcrypt truncate all passwords at 72 characters which means + that ``bcrypt(password_with_100_chars) == bcrypt(password_with_100_chars[:72])``. + The original ``BCryptPasswordHasher`` does not have any special handling and + thus is also subject to this hidden password length limit. + ``BCryptSHA256PasswordHasher`` fixes this by first first hashing the + password using sha256. This prevents the password truncation and so should + be preferred over the ``BCryptPasswordHasher``. The practical ramification + of this truncation is pretty marginal as the average user does not have a + password greater than 72 characters in length and even being truncated at 72 + the compute powered required to brute force bcrypt in any useful amount of + time is still astronomical. Nonetheless, we recommend you use + ``BCryptSHA256PasswordHasher`` anyway on the principle of "better safe than + sorry. + .. admonition:: Other bcrypt implementations There are several other implementations that allow bcrypt to be @@ -138,6 +156,7 @@ default PBKDF2 algorithm: 'myproject.hashers.MyPBKDF2PasswordHasher', 'django.contrib.auth.hashers.PBKDF2PasswordHasher', 'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher', + 'django.contrib.auth.hashers.BCryptSHA256PasswordHasher', 'django.contrib.auth.hashers.BCryptPasswordHasher', 'django.contrib.auth.hashers.SHA1PasswordHasher', 'django.contrib.auth.hashers.MD5PasswordHasher', @@ -194,8 +213,8 @@ from the ``User`` model. provide a salt and a hashing algorithm to use, if you don't want to use the defaults (first entry of ``PASSWORD_HASHERS`` setting). Currently supported algorithms are: ``'pbkdf2_sha256'``, ``'pbkdf2_sha1'``, - ``'bcrypt'`` (see :ref:`bcrypt_usage`), ``'sha1'``, ``'md5'``, - ``'unsalted_md5'`` (only for backward compatibility) and ``'crypt'`` + ``'bcrypt_sha256'`` (see :ref:`bcrypt_usage`), ``'bcrypt'``, ``'sha1'``, + ``'md5'``, ``'unsalted_md5'`` (only for backward compatibility) and ``'crypt'`` if you have the ``crypt`` library installed. If the password argument is ``None``, an unusable password is returned (a one that will be never accepted by :func:`check_password`). |