A Record That Carries Its Own Settings

The command you ran at the end of Lesson 3 printed different bytes on every run. To check a password next week, the server must compute the same bytes again, and that takes the same salt and the same n, r, and p. All four have to be stored with the hash. This lesson stores them in the simplest way there is: in one line of text.

One line of text

A password record in this course looks like this. It is one line of text; here it is broken after the salt to fit the page:

scrypt$16384$8$1$Iiddrf4ZE7Bp5ctR/ENjYg==$
SedCTnOCi3DaMFK3PxyvJVqZ0Bt9WC7EjAgXnWwxjuQ=

It has six parts, joined by $:

• the label scrypt, which says which function made the record. A later version of the service can then add another function and still tell old records from new ones;

• n, r, and p, as plain whole numbers: the cost this record was made with;

• the salt;

• the hash.

The salt and the hash are bytes, and a line of text cannot hold arbitrary bytes. So they go in as base64, with base64.b64encode(...).decode("ascii"). Standard base64 uses letters, digits, +, /, and =, and never $, so the separator cannot appear inside a part.

Other password libraries write records in the same spirit. If you ever see a stored value that starts $2b$12$, that is a record made by another password hash, bcrypt, with its cost in the second part.

make_record(password, *, n, r, p) builds this line: draw a new salt with new_salt(), hash with hash_password(...), and put the six parts together. An f-string does it in one line.

Notice what the record does not contain: the password. Everything in it is safe to store next to a user name. The salt is public by design, the settings are public, and the hash is the output of the slow function. A thief who reads the record has to guess, and every guess costs one scrypt call at the record’s settings.

Verify

verify_password(password, record) goes the other way.

1. Split the record on $. If that does not give six parts, or the first part is not scrypt, the text is not a record of this kind, and the answer is False.

2. Decode the salt and the stored hash with base64.b64decode(...).

3. Hash the password with hash_password(...), using the salt and the three numbers from the record. Use int(...) on the numbers: they come out of the split as text.

4. Compare the new hash with the stored one, and return the answer.

Step 3 has a trap. The settings to use are the record’s own, not today’s COST_N. A record made at n=4096 can only be reproduced at n=4096.

Step 4 is the second place in this project where a secret meets one expected value, after the tag in signing.py. So the rule of Chapter 2 applies: compare the two byte strings with hmac.compare_digest, and return what it returns.

A record is trusted data here. It comes from the server’s own state, not from a request, so verify_password does not defend against a record with absurd numbers in it. In the words of Chapter 1, a record never crosses the trust boundary inward. The password does, on every login.

Costs go up

Hardware gets faster every year, so a service raises its cost from time to time. Records made before the change stay at the old cost. That is why the cost is in the record: the service can hold records of different strength side by side, and can tell which is which.

needs_rehash(record, *, n) answers one question: was this record made at a lower cost than n? Read the record’s n from its second part and compare. Compare numbers, not text:

print("4096" < "16384", 4096 < 16384)

The comparison is “lower than”, not “different from”. A record that is stronger than today’s setting must never be replaced by a weaker one.

Replacing a weak record with a fresh one at today’s cost is called rehashing, and it has a catch: making a record takes the password, and the server does not have it. The simplest moment to upgrade is therefore a correct login, when the user has just sent the password. Lesson 6 does that. A service that cannot wait for every user to log in has another way, which this course names and does not build: it can wrap each old hash in the stronger function at once, and replace the wrapped record with a clean one at the next login.

Your task

In passwords.py, write make_record, verify_password, and needs_rehash as described above.

Then write one attack test. The attack is the observation from Lesson 1: in the leaked table, equal digests gave away that two users had the same password. In tests/test_attacks.py, below the Chapter 3 comment, write test_attack_equal_passwords_get_different_records. Make two records for the same password with passwords.make_record(...) at n=16, r=8, p=1, and assert that they differ. The low cost keeps the test fast, which is what the cost parameters are for.

Run the tests:

python -m pytest -q

The run ends with 1 failed, 5 passed. The one failure is still the Chapter 1 test. It turns green in Lesson 6.

Then press Check my work. A record now carries everything needed to check a password against it. The next lesson looks at what a login reveals when there is no record to check.