Overview
Canonicalization is reducing data to a single, standard form before validating or acting on it. Skipping it causes a whole class of bypasses, where the same value has multiple representations that fool naive checks. This lesson explains canonicalization.
Learning objectives
- Define canonicalization and why it matters.
- Explain how multiple encodings/representations bypass checks.
- Describe safe canonicalize-then-validate ordering.
Core concept
Canonicalization converts input into its canonical (standard) form so that equivalent inputs are represented identically. Many values have multiple representations — different character encodings, URL/percent-encoding, mixed case, alternate path forms (../, ..%2f, ./), or Unicode variants. If validation happens before canonicalization, an attacker can supply an alternate encoding that passes the check but resolves to something dangerous when later decoded/used.
The safe rule: canonicalize first, then validate, and use the canonical form consistently thereafter.
How it works
An application should first normalize input (decode encodings, resolve path forms, normalize Unicode/case as appropriate) into one canonical representation, and only then apply validation and use it. This prevents encoding-based bypasses, where, say, a blocked sequence is smuggled in an alternate encoding that the check misses but the underlying system decodes and acts on. Order matters: validating a non-canonical form is unreliable because the value can still transform afterward. Consistent canonical handling closes the gap between "what was checked" and "what is actually used."
Practical example
A file-access feature tries to block directory traversal by rejecting ../. An attacker instead supplies a percent-encoded form like ..%2f; the naive check does not match it, but when the platform later decodes the path, it becomes ../ and escapes the intended directory — a canonicalization failure. The fix is to canonicalize the path first (decode and resolve it to its real form) and then validate that it stays within the allowed directory. This pattern recurs in the path-traversal and input-validation defenses.
Cybersecurity relevance
Canonicalization failures enable filter and validation bypasses across many vulnerability classes — path traversal, injection, access-control checks, and more — because the security check and the eventual use disagree on the value's meaning. It is a subtle but common root cause of "the filter was bypassed." Defenders must canonicalize before validating and use safe, canonical-aware APIs; testers try alternate encodings and representations specifically to defeat checks that skipped canonicalization.
Common mistakes
- Validating before canonicalizing, so alternate encodings slip past checks.
- Handling only one representation (e.g. blocking
../but not its encoded forms). - Comparing non-normalized values (case/Unicode differences) in security decisions.
Key takeaways
- Canonicalization reduces input to a single standard form so equivalent inputs are represented identically.
- Values often have multiple representations (encodings, path forms, Unicode/case); validating before canonicalizing enables bypasses.
- Always canonicalize first, then validate, and use the canonical form consistently — a key defense against filter bypasses in traversal, injection, and access control.
Check your understanding
- Why must you canonicalize input before validating it rather than after?
- Give an example of how an alternate encoding can bypass a naive traversal filter.