Part 4 of 12 · 2 min read
Same arguments, same hash -- but only if you serialize them the same way
Two Python dictionaries that are logically equal can still produce two different strings once you call str() or json.dumps() on them, and a hash is only as consistent as the string that goes into it.
Think of two people writing the same shopping list in a different order on different-sized paper. The list is the same list. But if you compare the two pages byte-for-byte, they will not match.
canonical form is one standard serialization. Sorted keys, fixed separators -- so that logically equal arguments always hash equal no matter what order they happen to be written in. So that a type change (the integer 50 instead of the float 50.0) is treated as a genuinely different value rather than silently equal.
A worked example. The arguments {"order_id": "ORD-123456", "amount": 50.0, "currency": "USD"} and the same three keys written in reverse order both hash to the same value, so a token issued against one verifies successfully against the other -- key order is not part of the meaning, so canonicalization correctly ignores it. But amount: 50 (an int) and amount: 50.0 (a float) hash differently, so a token issued for the float is denied against the int -- a harmless-looking type change is treated as a changed argument and the call is rejected.
The key lines. From code/mini-approvals/approvals.py:
# from code/mini-approvals/approvals.py
def canonical(args):
"""Canonical JSON: sorted keys, no spaces. Numbers keep their type, so 50 and 50.0 and "50" hash differently (fail safe)."""
return json.dumps(args, sort_keys=True, separators=(",", ":"), ensure_ascii=True)
Read it as: sort_keys=True is what makes key order irrelevant. The absence of any numeric coercion is what makes the type distinction matter. One line buys you the forgiving behavior (reordered keys are fine) and the strict behavior (type changes are not) at the same time. That is because canonicalization standardizes exactly one thing, the string layout, and deliberately leaves the values themselves untouched.
Canonical form
Canonical form is one standard serialization -- sorted keys, fixed separators -- so equal arguments always hash equally.
Example: denying amount: 50 against a token issued for amount: 50.0 is a false rejection in the ordinary sense -- a human would call them the same refund -- but it's the price of failing safe: the alternative is a hashing scheme that has to decide which numeric differences are "close enough," and that decision is exactly where an attacker would look first.