Paseto Version 2

Encrypt

Given a message m, key k, and optional footer f.

1. Set header `h` to `v2.local.`
2. Generate 24 random bytes from the OS's CSPRNG.
3. Calculate BLAKE2b of the message `m` with the output of step 2 as the key, with an output length of 24. This will be our nonce, `n`. * This step is to ensure that an RNG failure does not result in a nonce-misuse condition that breaks the security of our stream cipher.
4. Pack `h`, `n`, and `f` together (in that order) using PAE. We'll call this `preAuth`.

5. Encrypt the message using XChaCha20-Poly1305, using an AEAD interface such as
   the one provided in libsodium.
   c = crypto_aead_xchacha20poly1305_encrypt(
       message = m
       aad = preAuth
       nonce = n
       key = k
   );
   

6. If `f` is: * Empty: return h || b64(n || c) * Non-empty: return h || b64(n || c) || `.` || base64url(f) * ...where || means "concatenate"

Decrypt

Given a message m, key k, and optional footer f.

1. If `f` is not empty, implementations MAY verify that the value appended to the token matches some expected string `f`, provided they do so using a constant-time string compare function.
2. Verify that the message begins with `v2.local.`, otherwise throw an exception. This constant will be referred to as `h`.
3. Decode the payload (`m` sans `h`, `f`, and the optional trailing period between `m` and `f`) from base64url to raw binary. Set: * `n` to the leftmost 24 bytes * `c` to the middle remainder of the payload, excluding `n`.
4. Pack `h`, `n`, and `f` together (in that order) using PAE. We'll call this `preAuth`

5. Decrypt `c` using `XChaCha20-Poly1305`, store the result in `p`.
   p = crypto_aead_xchacha20poly1305_decrypt(
      ciphertext = c
      aad = preAuth
      nonce = n
      key = k
   );
   

6. If decryption failed, throw an exception. Otherwise, return `p`.

Sign

Given a message m, Ed25519 secret key sk, and optional footer f (which defaults to empty string):

1. Set `h` to `v2.public.`
2. Pack `h`, `m`, and `f` together using PAE (pre-authentication encoding). We'll call this `m2`.

3. Sign `m2` using Ed25519 `sk`. We'll call this `sig`.
   sig = crypto_sign_detached(
       message = m2,
       private_key = sk
   );
   

4. If `f` is: * Empty: return "`h` || base64url(`m` || `sig`)" * Non-empty: return "`h` || base64url(`m` || `sig`) || `.` || base64url(`f`)" * ...where || means "concatenate" * Note: `base64url()` means Base64url from RFC 4648 without `=` padding.

Verify

Given a signed message sm, public key pk, and optional footer f (which defaults to empty string):

1. If `f` is not empty, implementations MAY verify that the value appended to the token matches some expected string `f`, provided they do so using a constant-time string compare function.
2. Verify that the message begins with `v2.public.`, otherwise throw an exception. This constant will be referred to as `h`.
3. Decode the payload (`sm` sans `h`, `f`, and the optional trailing period between `m` and `f`) from base64url to raw binary. Set: * `s` to the rightmost 64 bytes * `m` to the leftmost remainder of the payload, excluding `s`
4. Pack `h`, `m`, and `f` together using PAE. We'll call this `m2`.

5. Use Ed25519 to verify that the signature is valid for the message:
   valid = crypto_sign_verify_detached(
       signature = s,
       message = m2,
       public_key = pk
   );
   

6. If the signature is valid, return `m`. Otherwise, throw an exception.