|Classes of Scott Arciszewski||PHP PASeTo||docs/03-Implementation-Guide/01-Payload-Processing.md||Download|
All PASETO payloads must be a JSON-encoded object represented as a UTF-8 encoded string. The topmost JSON object should be an object, map, or associative array (select appropriate for your language), not a flat array.
If non-UTF-8 character sets are desired for some fields, implementors are encouraged to use Base64url encoding to preserve the original intended binary data, but still use UTF-8 for the actual payloads.
Type Safety with Cryptographic Keys
PASETO library implementations MUST implement some means of preventing type confusion bugs between different cryptography keys. For example:
It MUST NOT be possible for a user to take a known public key (used by public tokens), and generate a local token with the same key that any PASETO implementations will accept.
The following keys are reserved for use within PASETO. Users SHOULD NOT write arbitrary/invalid data to any keys in a top-level PASETO in the list below:
| Key | Name | Type | Example |
| ----- | ---------------- | -------- | --------------------------------------------------------- |
In the table above, DateTime means an ISO 8601 compliant DateTime string.
Any other claims can be freely used. These keys are only reserved in the top-level JSON object.
The keys in the above table are case-sensitive.
Implementors SHOULD provide some means to discourage setting invalid/arbitrary data to these reserved claims.
Some systems need to support key rotation, but since the payloads of a
Instead, users should store Key-ID claims (
For example, if you set the footer to
Implementations should feel free to provide a means to extract the footer from a token, before decryption, since the footer is used in the calculation of the authentication tag for the encrypted payload.
Users should beware that, until this authentication tag has been verified, the footer's contents are not authenticated.
While a key identifier can generally be safely used for selecting the cryptographic
key used to decrypt and/or verify payloads before verification, provided that they
IMPORTANT: Key identifiers MUST be independent of the actual keys used by Paseto.
For example, you MUST NOT just drop the public key into the footer for
Instead, it's recommended that implementors and users use a unique identifier for each key (independent of the cryptographic key's contents itself) that is used in a database or other key-value store to select the apppropriate cryptographic key. These search operations MUST fail closed if no valid key is found for the given key identifier.
Future Changes to Payload Processing
The payload processing SHOULD NOT change after version 1.0.0 of the reference implementation has been tagged, signed, and released; only the cryptography protocols will receive new versions.
In the event that this turns out to not be true, we will change the first letter
of the version identifier (
However, we hope to never need to do this.