diff options
Diffstat (limited to 'docs/topics/auth/passwords.txt')
| -rw-r--r-- | docs/topics/auth/passwords.txt | 30 |
1 files changed, 30 insertions, 0 deletions
diff --git a/docs/topics/auth/passwords.txt b/docs/topics/auth/passwords.txt index 29da3ae1d1..15d9a56ba2 100644 --- a/docs/topics/auth/passwords.txt +++ b/docs/topics/auth/passwords.txt @@ -194,6 +194,14 @@ sure never to *remove* entries from this list. If you do, users using unmentioned algorithms won't be able to upgrade. Passwords will be upgraded when changing the PBKDF2 iteration count. +Be aware that if all the passwords in your database aren't encoded in the +default hasher's algorithm, you may be vulnerable to a user enumeration timing +attack due to a difference between the duration of a login request for a user +with a password encoded in a non-default algorithm and the duration of a login +request for a nonexistent user (which runs the default hasher). You may be able +to mitigate this by :ref:`upgrading older password hashes +<wrapping-password-hashers>`. + .. _wrapping-password-hashers: Password upgrading without requiring a login @@ -283,6 +291,28 @@ Include any other hashers that your site uses in this list. .. _bcrypt: https://en.wikipedia.org/wiki/Bcrypt .. _`bcrypt library`: https://pypi.python.org/pypi/bcrypt/ +.. _write-your-own-password-hasher: + +Writing your own hasher +----------------------- + +.. versionadded:: 1.8.10 + +If you write your own password hasher that contains a work factor such as a +number of iterations, you should implement a +``harden_runtime(self, password, encoded)`` method to bridge the runtime gap +between the work factor supplied in the ``encoded`` password and the default +work factor of the hasher. This prevents a user enumeration timing attack due +to difference between a login request for a user with a password encoded in an +older number of iterations and a nonexistent user (which runs the default +hasher's default number of iterations). + +Taking PBKDF2 as example, if ``encoded`` contains 20,000 iterations and the +hasher's default ``iterations`` is 30,000, the method should run ``password`` +through another 10,000 iterations of PBKDF2. + +If your hasher doesn't have a work factor, implement the method as a no-op +(``pass``). Manually managing a user's password =================================== |