PASETO Footer — kid Hints and Authenticated Metadata

PASETO's optional footer is a powerful feature that's often misunderstood. It is the fourth, optional segment of a token (vN.purpose.payload.footer), is authenticated by the signature/MAC, but is never encrypted — even in v*.local tokens.

Why a separate footer:

A footer carries data that the verifier needs to read before running cryptographic operations. The canonical example is the kid (key ID) hint: if you rotate signing keys and need to support multiple keys simultaneously, the verifier must figure out which key to use before it can verify. Putting kid in the encrypted payload doesn't work for v4.local (you'd need the key to read the kid that tells you which key to use). Putting it in the footer solves this elegantly.

Format:

The footer is Base64url-encoded raw bytes. By convention, it's a small JSON object:

{ "kid": "key-2026-01" }

But it can be any byte sequence — a UUID, a domain name, a service identifier, anything authenticated.

Authentication, not confidentiality:

The footer is included in PASETO's pre-authentication encoding (PAE), so any tampering with it invalidates the signature/tag. But it travels in clear: anyone reading the wire-format token can read your footer. Don't put secrets there. Do put routing/dispatch information there.

Implicit assertions vs footer:

PASETO v3/v4 added "implicit assertions" — additional bytes that the issuer and verifier both know but that aren't part of the wire format. If your kid never needs to be on the wire (because both sides know it from configuration), an implicit assertion is even safer than a footer.

Common pitfalls:

Don't try to JSON-parse a footer that wasn't written as JSON — many systems use plain strings. Always treat footer-derived kid lookups as untrusted input even though they're authenticated; an attacker could replay an old token with an old (but valid) kid.