Canonicalisation

What it means

Canonicalisation means converting input into one standard, simplest form before you use it or judge it. The same thing can often be written many ways: a folder path with dots and slashes, a URL with percent signs, text in different character encodings. The canonical form is the single agreed way to write it.

The rule that follows is simple. Canonicalise first, then validate. If you check first and convert later, you checked something different from what you ended up using. Without it, two checks can look at the same input and see two different things, and an attacker only needs one of them to be fooled. The goal is for the check and the use to look at identical text.

Why it matters

Getting the order wrong is a classic route past security checks. A filter that blocks ../ can be fooled by an encoded form that only turns into ../ after decoding, which leads to path traversal and files outside the intended folder. The same trick works on URLs, filenames and usernames.

Double encoding is a related trick: a value decoded twice, once by a gateway and once by the app. The risk is a data leak or worse, and it is easy to miss since each component looks correct alone. See also input validation.

How it shows up

You meet it in file handling, URL routing, redirects, access rules that match on paths, and anywhere text is decoded more than once. Different layers, such as a proxy, a framework and the operating system, may each decode input in their own way.

Use your platform's function to resolve a path to its real form, then confirm the result sits inside the folder you meant. Decode once, at one place, and validate the result against an allowlist. Test by sending encoded, double-encoded and mixed-case versions of every value that a rule depends on.