[1.8.x] Fixed CVE-2016-2513 -- Fixed user enumeration timing attack during login.

This is a security fix.

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
 ===================================