# Password Storage Lab — PBKDF2 and scrypt in Python, Upgrading Old Hashes, Peppers and Reset Tokens

Source: https://skills101.in/learn/web-security/websec-password-storage-pbkdf2-lab — Skills101 free tutorial (Web Security (OWASP Top 10)). Updated 2026-11-21.

The [passwords and authentication](https://skills101.in/learn/web-security/password-hashing-authentication) lesson explained **why** passwords need salted, slow hashes. This lab is the practical follow-up: you will build the pieces a real login system needs, using only Python's standard library (`hashlib`, `hmac`, `secrets`). Everything here is **defensive** — it is how you protect your own users if your database is ever copied.

## 1. Why "slow" matters, in numbers

When a database leaks, attackers take each stored hash and try likely passwords from a list, hashing each guess the same way. Your only control is **how much each guess costs**.

PBKDF2 repeats a keyed hash (HMAC-SHA256) many times. Each HMAC uses two SHA-256 computations, so one PBKDF2 guess with 600,000 iterations costs about **1.2 million** SHA-256 computations instead of one. The numbers below use an **assumed** attacker speed, chosen only to show the ratio; real speeds depend on the hardware.

```python
ASSUMED_SHA256_PER_SECOND = 10 ** 9      # an assumption for illustration, not a measured figure
WORDLIST = 10 ** 7                       # ten million candidate passwords

for name, cost in [("SHA-256 (1 hash)", 1), ("PBKDF2 100,000 iterations", 2 * 100_000),
                   ("PBKDF2 600,000 iterations", 2 * 600_000)]:
    seconds = WORDLIST * cost / ASSUMED_SHA256_PER_SECOND
    print(f"{name:27} {seconds:>12,.2f} seconds per user ({seconds / 86400:,.2f} days)")
```

```text
SHA-256 (1 hash)                    0.01 seconds per user (0.00 days)
PBKDF2 100,000 iterations       2,000.00 seconds per user (0.02 days)
PBKDF2 600,000 iterations      12,000.00 seconds per user (0.14 days)
```

With a fast hash the whole list is tried in a fraction of a second **per user**. With 600,000 iterations the same work takes days per user — and because every user has a different salt, the attacker must repeat it for every account. 600,000 iterations for PBKDF2-HMAC-SHA256 is the figure the OWASP Password Storage Cheat Sheet recommends at the time of writing; check the current guidance when you build a real system, because recommended costs rise as hardware gets faster.

![Relative cost of trying ten million guesses against one user under an assumed attacker speed: a single SHA-256 takes about 0.01 seconds, PBKDF2 with 100,000 iterations about 2,000 seconds and PBKDF2 with 600,000 iterations about 12,000 seconds](https://skills101.in/learn-img/web-security/guess-cost.svg)

## 2. Salt and cost change the output

A hash depends on **four** inputs: the algorithm, the password, the salt and the cost. Change any one and the output changes completely. Here the salt is fixed so the output is repeatable; in real code the salt comes from `os.urandom(16)` or `secrets.token_bytes(16)`.

```python
import hashlib

pw = "Monsoon@Jaipur7".encode()
for salt, iterations in [(b"salt-AAAAAAAAAAA", 600_000), (b"salt-BBBBBBBBBBB", 600_000), (b"salt-AAAAAAAAAAA", 600_001)]:
    digest = hashlib.pbkdf2_hmac("sha256", pw, salt, iterations)
    print(salt.decode(), f"{iterations:>7}", digest.hex()[:24], "...")
```

```text
salt-AAAAAAAAAAA  600000 7a90b363ffd513d057ade7f2 ...
salt-BBBBBBBBBBB  600000 78c39f2474d857ee7b06c8f2 ...
salt-AAAAAAAAAAA  600001 442a4748d3ee44052700cf26 ...
```

This is why the **salt and the iteration count must be stored with the hash**. Without them you cannot verify the password later.

## 3. A self-describing storage format

Store everything needed to verify in one string, like `pbkdf2_sha256$600000$<salt hex>$<hash hex>`. Django, Werkzeug and many other frameworks use the same idea. The format lets you **change settings later** without breaking old accounts.

![Login flow with hash upgrading: look up the stored string, read its algorithm and cost, verify the typed password; on failure reject with a generic message; on success, if the algorithm or cost is out of date, hash the password again with current settings and save it, then log the user in](https://skills101.in/learn-img/web-security/rehash-flow.svg)

```python
import hashlib, hmac, os

ALGO, ITERATIONS = "pbkdf2_sha256", 600_000

def hash_password(password):
    salt = os.urandom(16)
    digest = hashlib.pbkdf2_hmac("sha256", password.encode(), salt, ITERATIONS)
    return f"{ALGO}${ITERATIONS}${salt.hex()}${digest.hex()}"

def verify(password, stored):
    algo, iterations, salt_hex, digest_hex = stored.split("$")
    if algo != ALGO:
        return False
    digest = hashlib.pbkdf2_hmac("sha256", password.encode(), bytes.fromhex(salt_hex), int(iterations))
    return hmac.compare_digest(digest.hex(), digest_hex)

def needs_rehash(stored):
    algo, iterations, *_ = stored.split("$")
    return algo != ALGO or int(iterations) < ITERATIONS

stored = hash_password("Monsoon@Jaipur7")
print("fields:", len(stored.split("$")), "| starts with:", stored[:21])
print("right password:", verify("Monsoon@Jaipur7", stored))
print("wrong password:", verify("monsoon@jaipur7", stored))
print("needs rehash:  ", needs_rehash(stored))
print("old 100k hash needs rehash:", needs_rehash("pbkdf2_sha256$100000$00$00"))
```

```text
fields: 4 | starts with: pbkdf2_sha256$600000$
right password: True
wrong password: False
needs rehash:   False
old 100k hash needs rehash: True
```

## 4. Upgrading old hashes when users log in

Real systems often inherit weak hashes: an old site that used plain `sha256(password)`, or PBKDF2 with too few iterations. You **cannot** convert these directly, because you do not know the passwords. But at the moment a user logs in successfully, you briefly have the real password — so you can hash it again with current settings.

```python
import hashlib, hmac, os

ALGO, ITERATIONS = "pbkdf2_sha256", 600_000

def pbkdf2(password, salt, iterations):
    return hashlib.pbkdf2_hmac("sha256", password.encode(), salt, iterations).hex()

def hash_password(password):
    salt = os.urandom(16)
    return f"{ALGO}${ITERATIONS}${salt.hex()}${pbkdf2(password, salt, ITERATIONS)}"

def verify(password, stored):
    algo, rest = stored.split("$", 1)
    if algo == "sha256":                                   # legacy: unsalted fast hash
        return hmac.compare_digest(hashlib.sha256(password.encode()).hexdigest(), rest)
    if algo == ALGO:
        iterations, salt_hex, digest_hex = rest.split("$")
        return hmac.compare_digest(pbkdf2(password, bytes.fromhex(salt_hex), int(iterations)), digest_hex)
    return False

def needs_rehash(stored):
    parts = stored.split("$")
    return parts[0] != ALGO or int(parts[1]) < ITERATIONS

users = {
    "asha": "sha256$" + hashlib.sha256(b"chai-and-code-42").hexdigest(),       # from the old site
    "ravi": f"{ALGO}$100000$" + "ab" * 16 + "$" + pbkdf2("Ravi#Placement26", bytes.fromhex("ab" * 16), 100_000),
}

def login(username, password):
    stored = users.get(username)
    if stored is None or not verify(password, stored):
        return "Incorrect username or password"
    if needs_rehash(stored):
        users[username] = hash_password(password)           # upgrade now, while we know the password
        return f"welcome {username} (hash upgraded)"
    return f"welcome {username}"

print(login("asha", "wrong"))
print(login("asha", "chai-and-code-42"))
print(login("asha", "chai-and-code-42"))
print(login("ravi", "Ravi#Placement26"))
print("stored formats now:", {u: h.split("$")[:2] for u, h in users.items()})
```

```text
Incorrect username or password
welcome asha (hash upgraded)
welcome asha
welcome ravi (hash upgraded)
stored formats now: {'asha': ['pbkdf2_sha256', '600000'], 'ravi': ['pbkdf2_sha256', '600000']}
```

Notice three details:

- The failure message is the **same** for an unknown user and a wrong password, so attackers cannot use it to find which accounts exist.
- The upgrade happens **only after** a successful verification.
- Users who never log in again keep their old hashes. Common options are to **wrap** the old hash immediately (store `pbkdf2(sha256(password))` and verify the same way) or to force a password reset after a deadline.

## 5. scrypt: also costly in memory

PBKDF2 makes each guess slow but uses almost no memory, which suits attackers with GPUs and custom chips. **scrypt** (and Argon2id, available through the `argon2-cffi` package) also require a large block of **memory** per guess, which is much harder to run in parallel. Python's `hashlib.scrypt` needs no extra install:

```python
import hashlib

salt = b"fixed-demo-salt!"           # real code: os.urandom(16)
n, r, p = 2 ** 17, 8, 1               # memory needed is about 128 * n * r bytes
memory_mb = 128 * n * r / 2 ** 20
key = hashlib.scrypt(b"Monsoon@Jaipur7", salt=salt, n=n, r=r, p=p, maxmem=256 * 2 ** 20, dklen=32)
print(f"memory per guess: about {memory_mb:.0f} MB")
print("scrypt key:", key.hex()[:32], "...")
```

```text
memory per guess: about 128 MB
scrypt key: a5c398d857697899a425dd6ca1135836 ...
```

The parameters n = 2¹⁷, r = 8, p = 1 match the OWASP cheat sheet's scrypt example. Store them in the hash string, just like the iteration count.

## 6. Pepper and Unicode: two extra layers

**Pepper.** A pepper is a secret key kept **outside** the database (an environment variable or a secrets manager), mixed in with HMAC before hashing. If only the database leaks, the attacker cannot even start guessing. It is an extra layer, not a replacement for salts, and you must plan how to rotate it.

**Unicode normalisation.** "é" can be stored as one character or as "e" plus an accent mark. They look identical but are different bytes, so a user who types the same password on another device might fail to log in. Normalising (NFKC is the common choice) before hashing avoids this.

```python
import hashlib, hmac, unicodedata

PEPPER = b"from-env-or-secrets-manager"          # never stored in the database
salt = b"fixed-demo-salt!"

def prepare(password):
    normalised = unicodedata.normalize("NFKC", password)
    return hmac.new(PEPPER, normalised.encode(), hashlib.sha256).digest()

def store(password):
    return hashlib.pbkdf2_hmac("sha256", prepare(password), salt, 600_000).hex()

composed, decomposed = "Café-2026", "Café-2026"
print("same text on screen:", composed, decomposed)
print("same bytes:", composed.encode() == decomposed.encode())
print("same hash after NFKC:", store(composed) == store(decomposed))
```

```text
same text on screen: Café-2026 Café-2026
same bytes: False
same hash after NFKC: True
```

## 7. Password reset tokens: a fast hash is fine here

A reset link contains a random token. Store only a **hash** of it, so a database leak does not give attackers working reset links. Here a single SHA-256 is enough, because the token is **256 random bits**, not a human-chosen password — no wordlist can guess it.

```python
import hashlib, hmac, secrets

def new_reset_token():
    token = secrets.token_urlsafe(32)                    # 32 random bytes, sent in the email link
    return token, hashlib.sha256(token.encode()).hexdigest()

def check_reset(token, stored_hash, expires_at, now):
    if now > expires_at:
        return "link expired"
    ok = hmac.compare_digest(hashlib.sha256(token.encode()).hexdigest(), stored_hash)
    return "ok: let the user set a new password" if ok else "invalid link"

token, stored_hash = new_reset_token()
print("token length:", len(token), "characters")
print(check_reset(token, stored_hash, expires_at=1000, now=400))
print(check_reset(token[:-1] + "x", stored_hash, expires_at=1000, now=400))
print(check_reset(token, stored_hash, expires_at=1000, now=1600))
```

```text
token length: 43 characters
ok: let the user set a new password
invalid link
link expired
```

Also: make tokens **single-use** (delete the hash after use), expire them within minutes to an hour, and end the user's other sessions after the password changes.

## 8. Test it

Password code fails silently — a bug that accepts every password looks fine until someone notices. A few assertions catch the dangerous mistakes:

```python
import hashlib, hmac, os

def hash_password(pw, iterations=600_000):
    salt = os.urandom(16)
    return f"pbkdf2_sha256${iterations}${salt.hex()}${hashlib.pbkdf2_hmac('sha256', pw.encode(), salt, iterations).hex()}"

def verify(pw, stored):
    algo, it, salt, digest = stored.split("$")
    return hmac.compare_digest(hashlib.pbkdf2_hmac("sha256", pw.encode(), bytes.fromhex(salt), int(it)).hex(), digest)

h1, h2 = hash_password("Secret#123"), hash_password("Secret#123")
assert verify("Secret#123", h1), "right password must pass"
assert not verify("secret#123", h1), "case matters"
assert not verify("", h1), "empty password must fail"
assert h1 != h2, "same password must give different hashes (random salt)"
assert "Secret#123" not in h1, "the password must never appear in storage"
print("all password tests passed")
```

```text
all password tests passed
```

## Common mistakes

- Writing your own scheme (`sha256(salt + password)` repeated in a loop) instead of PBKDF2, scrypt, bcrypt or Argon2id from a trusted library.
- Not storing the algorithm and cost, which makes upgrading impossible.
- Upgrading hashes **before** checking the password, or never upgrading at all.
- Using one global salt for everyone. Salts must be random and different per user.
- Keeping the pepper in the same database as the hashes.
- Storing reset tokens in plain text, or letting them work more than once.
- Using bcrypt without knowing that it only uses the first 72 bytes of the password.

## Quick recap

- Cost per guess is your defence: PBKDF2 at 600,000 iterations makes each guess over a million times more expensive than one SHA-256.
- Store `algorithm$cost$salt$hash`; verify with `hmac.compare_digest`.
- Upgrade weak or legacy hashes right after a successful login; give the same error for unknown users and wrong passwords.
- scrypt and Argon2id add memory cost; a pepper and NFKC normalisation are useful extra layers.
- Reset tokens are random, so a SHA-256 of the token is fine — keep them single-use and short-lived.
- Test that wrong, empty and differently-cased passwords fail and that salts differ.


Practice quiz and free certificate: https://skills101.in/learn/web-security/websec-password-storage-pbkdf2-lab