Fixed #29289 -- Clarified PasswordResetTokenGenerator comment regarding the data hashed to generate tokens.

Thanks Luke Plant for the draft text.

1 files changed, 17 insertions, 10 deletions

diff --git a/django/contrib/auth/tokens.py b/django/contrib/auth/tokens.py
index 2272cd2415..9aa0a5262a 100644
--- a/django/contrib/auth/tokens.py
+++ b/django/contrib/auth/tokens.py
@@ -55,23 +55,30 @@ class PasswordResetTokenGenerator:
         # timestamp is number of days since 2001-1-1.  Converted to
         # base 36, this gives us a 3 digit string until about 2121
         ts_b36 = int_to_base36(timestamp)
-
-        # By hashing on the internal state of the user and using state
-        # that is sure to change (the password salt will change as soon as
-        # the password is set, at least for current Django auth, and
-        # last_login will also change), we produce a hash that will be
-        # invalid as soon as it is used.
-        # We limit the hash to 20 chars to keep URL short
-
         hash = salted_hmac(
             self.key_salt,
             self._make_hash_value(user, timestamp),
             secret=self.secret,
-        ).hexdigest()[::2]
+        ).hexdigest()[::2]  # Limit to 20 characters to shorten the URL.
         return "%s-%s" % (ts_b36, hash)
 
     def _make_hash_value(self, user, timestamp):
-        # Ensure results are consistent across DB backends
+        """
+        Hash the user's primary key and some user state that's sure to change
+        after a password reset to produce a token that invalidated when it's
+        used:
+        1. The password field will change upon a password reset (even if the
+           same password is chosen, due to password salting).
+        2. The last_login field will usually be updated very shortly after
+           a password reset.
+        Failing those things, settings.PASSWORD_RESET_TIMEOUT_DAYS eventually
+        invalidates the token.
+
+        Running this data through salted_hmac() prevents password cracking
+        attempts using the reset token, provided the secret isn't compromised.
+        """
+        # Truncate microseconds so that tokens are consistent even if the
+        # database doesn't support microseconds.
         login_timestamp = '' if user.last_login is None else user.last_login.replace(microsecond=0, tzinfo=None)
         return str(user.pk) + user.password + str(login_timestamp) + str(timestamp)