PASERK: Platform-Agnostic Serialized Keys

PASERK is an extension to PASETO that provides key-wrapping and serialization.

Motivation

PASETO provides two types of tokens (called a purpose) in each of its versions:

Purpose	Cryptographic Operation
local	Symmetric-key authenticated encryption with additional data (AEAD)
public	Asymmetric-key digital signatures (no encryption)

These two token modes solve at least 80% of use cases for secure tokens. You can even solve unencrypted symmetric-key authentication by storing your claims in the unencrypted footer, rather than encrypting them.

The use-cases that PASETO doesn't address out of the box are:

• Key-wrapping
• Asymmetric encryption
• Password-based key encryption

PASERK aims to provide an answer for these circumstances, as well as provide a consistent standard for the encoding of PASETO keys.

PASERK

A serialized key in PASERK has the format:

k[version].[type].[data]

Where [version] is an integer, [data] is the (typically base64url-encoded) payload data, and [type] is one of the items in the following table:

PASERK Type	Meaning	PASETO Compatibility	[data] Encoded?	Safe in Footer?
lid	Unique Identifier for a separate PASERK for local PASETOs.	local	Yes	Yes
local	Symmetric key for local tokens.	local	Yes	No
seal	Symmetric key wrapped using asymmetric encryption.	local	Yes	Yes
local-wrap	Symmetric key wrapped by another symmetric key.	local	No	Yes
local-pw	Symmetric key wrapped using password-based encryption.	local	Yes	No
sid	Unique Identifier for a separate PASERK for public PASETOs. (Secret Key)	public	Yes	Yes
public	Public key for verifying public tokens.	public	Yes	No
pid	Unique Identifier for a separate PASERK for public PASETOs. (Public Key)	public	Yes	Yes
secret	Secret key for signing public tokens.	public	Yes	No
secret-wrap	Asymmetric secret key wrapped by another symmetric key.	public	No	Yes
secret-pw	Asymmetric secret key wrapped using password-based encryption.	public	Yes	No

The version of a PASERK MUST match the version of the PASETO it's used with. For example, a k2.local. PASERK must be used with v2.local. tokens. Cross-version support is explicitly NOT permitted.

Each type is a composition of one or more operations.

As one of the design criteria, it MUST be safe for users to store the ID PASERK for a PASETO key (resulting in lid, sid, or pid types) in the footer (or, in v3/v4 of PASETO, as an implicit assertion). These types SHOULD be stored in the kid field in the footer, if the footer is JSON encoded.

Any of these PASERK types MAY be stored in the PASETO footer (in the wpk claim), because the encoded key is also wrapped with additional layers of cryptography: local-wrap, seal, secret-wrap. The wrapping key MUST NOT be disclosed.

All other types MUST NOT be included in a PASETO footer.

Examples of Valid PASERKs in a PASETO Footer

{"kid":"k4.lid.iVtYQDjr5gEijCSjJC3fQaJm7nCeQSeaty0Jixy8dbsk"}

{"kid":"k4.pid.9ShR3xc8-qVJ_di0tc9nx0IDIqbatdeM2mqLFBJsKRHs"}

{"kid":"k4.sid.gHYyx8y5YzqKEZeYoMDqUOKejdSnY_AWhYZiSCMjR1V5"}

The PASERK key ID is always okay to include in a PASETO footer.

---

{"wpk":"k4.local-wrap.pie.pu-fBxwoXrICYjeumh77cJ6la4svNGrjshQ7W_ygiJzm80LQBB1e6yqODDq6HO8c0UNY_dzLkzZC62Z81eleoIYUChwymEx23KbTQDinWaOQoKkRantNkrD5o0eo8iCS"}

{"wpk":"k4.secret-wrap.pie.jLhVAJYWaOcKiFvnKv6kFEQxSGV9BQuW1Qt4jRwr6yHiNeQf2h1GQ0czBJZpveX5T0R0YZv2OEenf8uyLqwamDJUbtS-GdYp_TXT1OJCwGJb2UpEHvcSOciH2PVCEiTrLM9n_mAI4SWXDfw4xYenmINDhi8EiPaPKvsOU64YBvY"}

Wrapped keys are encrypted. As long as the wrapping key is confidential, this is safe.

---

{"wpk":"k4.seal.3-VOL4pX5b7eV3uMhYHfOhJNN77YyYtd7wYXrH9rRucKNmq0aO-6AWIFU4xOXUCBk0mzBZeWAPAKrvejqixqeRXm-MQXt8yFGHmM1RzpdJw80nabbyDIsNCpBwltU-uj"}

Sealed keys are wrapped using public-key encryption. As long as the unwrapping key (asymmetric secret key) is confidential, this is safe.

Examples of Invalid PASERKs in a PASETO Footer

{"wpk":"k4.local.cHFyc3R1dnd4eXp7fH1-f4CBgoOEhYaHiImKi4yNjo8"}

This is a local type, and it is forbidden. Critically, it would disclose a symmetric key if included in an unencrypted PASETO footer.

{"wpk":"k3.secret.cHFyc3R1dnd4eXp7fH1-f4CBgoOEhYaHiImKi4yNjo-QkZKTlJWWl5iZmpucnZ6f"}

This is a secret type, and it is forbidden. Critically, it would disclose an asymmetric secret key if included in an unencrypted PASETO footer.

{"wpk":"k3.public.AnBxcnN0dXZ3eHl6e3x9fn-AgYKDhIWGh4iJiouMjY6PkJGSk5SVlpeYmZqbnJ2enw"}

This is forbidden by the PASETO specification:

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 a public token and have the recipient use the provided public key. Doing so would allow an attacker to simply replace the public key with one of their own choosing, which will cause the recipient to simply accept any signature for any message as valid, which defeats the security goals of public-key cryptography.

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.

Even though a public key might seem harmless, it risks the encouragement of in-band negotiation. This could result in users trusting the attacker-provided public key associated with a PASETO, which would bypass the security offered by the security token. Therefore, this use case MUST NOT ever be permitted.

---

{"wpk":"k4.local-pw._bru5tnkPSFXOtKhBTmW4gAAAAAEAAAAAAAAAgAAAAGKI3PyFS2vyQ9o5qowCR_GUXskLmdV1bjjc3vqnbwN7hVG1lAUCGjElTGIoH-K6lnkHnP4uaFBKWEtB3xFEGzAjzBSnl_JBmwLYK5jstjAV6LnJm_NOt0j"}

{"wpk":"k4.secret-pw.dkyi7kfzHnVTCqTq1AvLyQAAAAAQAAAAAAAAAwAAAAFWNLgB_yXNkk4W9NiXgeTkNnB3Vjuk_-TFQ-vMUxNX-Ha3k42djov9rHVykMHkrSGUemYFwpot9uNHnXOWtJCVIwdYAwZmt_uRSJ2rRTElanT6mWXojuBUy2k1lxD-iZ10pVPkJ-Kvv_SLEhLQ8RS7wqFW8RfFGyw"}

Password-based key-wrapping is provided in PASERK for systems that need password-protected cryptographic secrets, but password-protected keys MUST NOT be included in a PASETO footer.

PASERK Implementations

• PHP (Reference Implementation)