Version 2.4.2

• Updated Easy-ECC minimum version to 1.x
• Updated README to mention PASERK.

Version 2.4.1

• #155 - Fixed minor nits (docblocks, exception propagations) discovered during routine code review.
• Additionally, while not security-related: Encryption/MAC keys are now wiped as soon as possible in V1, V3, and V4.
  • V2 doesn't need this change.

Version 2.4.0

• #151 - Fixed IdentifiedBy to check jti claim
• #152 - Docblocks allow mixed-value claims
• #154 - Add isForVersion() helper to PASETO Key objects.
  • For example: $key->isForVersion(new Version4) will return true if the key is intended for PASETO v4, and false otherwise.

Version 2.3.0

• PASETO v1 and v2 protocols are now deprecated, please use v3 and v4 in new code.
• #147 - Removed dead code due to a previous optimization (Thanks @arokettu!)

Version 2.2.0

• Added encodePem() to AsymmetricSecretKey and AsymmetricPublicKey.
• The default behavior of AsymmetricSecretKey::encode() for Version3 is to return the base64url encoding of the secret scalar, not of the PEM-encoded string.
• #145: Throw an exception if a message is too short

Version 2.1.1

• Version3 now supports raw 48-byte (not PEM-encoded) secret keys.
• We now include negative tests.

Version 2.1.0

This is a feature release for the PHP implementation of PASETO.

New Features

• Unless otherwise specified by the user, expiration is enforced by default in both the Builder and Parser classes.
  You can disable this default by invoking ->setNonExpiring(true) on your Builder or Parser objects.
• Added support for Key Rings. (#137)
• Expanded unit tests to cover algorithm lucidity

Version 2.0.0

This is v2.0.0 of the PHP implementation of PASETO.

At a glance:

• This library now requires PHP 7.1 or newer.
• This library now requires the GMP extension installed (due to an additional dependency).
• The default protocol has been changed from Version2 to Version4. If you weren't defining this in your code and relying on the default settings, you will need to be explicit before you upgrade.

A lot has changed; please read carefully.

We've moved the PASETO Specification to another repository. In this updated specification, we have defined two new PASETO protocol versions.

• Version 3 is the successor to Version 1 for systems that MUST only use NIST-approved algorithms.
• Version 4 is the successor to Version 2 for systems that want to use the algorithms provided by libsodium over the choices made by NIST and/or the US National Security Agency.

If you'd like to read the full rationale for the design decisions made in Versions 3 and 4, these have been documented clearly here.

Although we strongly recommend migrating to the new versions (v1 -> v3, v2 -> v4), you are fine to continue using v1/v2 if the following assumptions hold true:

• PHP's random_bytes() is working correctly (i.e. talking to the kernel's CSPRNG).
• For v1.public tokens:
  • You don't require Exclusive Ownership (PDF) for your application
• For v2.local tokens:
  • You will only use one key at a time, and attackers cannot switch between them (i.e. no Key IDs in the footer)

If any of these assumptions are invalid, you MUST use the new versions to get the security properties you need out of PASETO. See the brief yet concise Migration Guide for more information.

Questions and Answers

What if I'm unsure if I should migrate to the newer version?

If you aren't 100% sure you don't need the security properties offered by v3/v4, and have nothing preventing you from making the change (i.e. a hard dependency on RSA keys), then you should lean towards migrating.

It's better to have it and not need it, than need it and not have it.

Is PASETO v1/v2 vulnerable?

Generally, no. That's why we aren't immediately deprecating their use. The complete answer requires a bit of nuance:

• AEAD modes based on Polynomial MACs, such as AES-GCM and XChaCha20-Poly1305, do not offer message- or key-commitment. This means it's possible to construct two different plaintexts that, under two different keys, yield the same (nonce, ciphertext, tag) tuple. This means that a given PASETO v2 token might decode to two different payloads, under two different keys.

  • If you're using v2.local tokens with some sort of homemade key-wrapping scheme that doesn't provide key-commitment, then YES, you SHOULD treat this as a sev:low vulnerability in your application. The relevant attack is complex and usually requires some degree of privileged access to pull off.
    • The fix is to migrate to Version4.
    • If you're using Key-IDs, then you probably want to migrate just in case, but we're not aware of any actual risks when the attacker can only switch between a finite set of possible keys outside their control.
    • If you need an interim mitigation (because, for some reason, you can't just migrate), it's possible to by including a KDF output of your symmetric key. (See below.)
  • If you aren't, it's not really a big deal. Carry on.

• @thaidn disclosed an unfortunate failure mode that's unlikely to ever happen: If the CSPRNG returns a predictable output (for example, all NUL bytes), then the derived nonce will be the hash of your plaintext payload. RNG failures with PHP 7's CSPRNG are fatal errors, so a silently-failing CSPRNG is very unlikely, but if it ever did happen, attackers could leak your plaintext by brute-forcing the hash that produces the nonce. This is only relevant to v1.local and v2.local.

  • If it ever did happen in general, it would break the security of key/nonce generation in all cryptographic applications.

• How RSA signatures are used in PASETO v1.public tokens do not offer Exclusive Ownership. Learn more about why it matters.

  Bottom-line: digital signatures yield guarantees about a message for a given public key, not the other way round.
  -- Thomas Pornin

These are all nuisances we sought to fix in Version 3 and Version 4. As a result, the new versions offer a more robust argument for their security in a wider range of real-world use cases.

What would a Version2 mitigation look like?

Use this to commit/verify that the same key was used for a given PASETO:

<?php
function v2key_commit(SymmetricKey $key): string {
    return sodium_bin2hex(
        sodium_crypto_generichash('MITIGATION_COMMIT_KEY', $key->raw())
    );
}

function v2key_verify(SymmetricKey $key, string $commitment): bool {
    $calc = v2key_commit($key);
    return hash_equals($calc, $commitment);
}

Just store the commitment hash inside the footer, then verify it before parsing. Since this will be bundled with the token (and cryptographically bound to it through the Poly1305 authentication tag), even if an attacker can perform some trickery, v2key_verify() will return false if the target is decrypting the token with the wrong key.

Is there a CVE identifier for any of those issues?

No, a CVE ID is not appropriate for non-vulnerabilities.

If any system is specifically impacted by the Poly1305 issue in v2.local tokens, and sets up the condition that makes the complex attack possible, then a CVE would be appropriate for that specific application. This generally means "wrote our own key-wrapping scheme based on AES-GCM or ChaCha20-Poly1305".

Although the RNG failure mode sounds scary, the security of your entire system depends on the CSPRNG not failing. This is sort of like getting a DoS attack to work from root. You will almost certainly never be impacted by this.

If any system is affected by the lack of Exclusive Ownership in v1.public tokens, then a) we want to hear about this system and b) a CVE definitely would be appropriate for whatever was built--but EO was never a stated goal for v1.public tokens, so its absence doesn't qualify as a vulnerability in PASETO.

We believe that requesting a CVE identifier out of an abundance of caution will only create alert fatigue for the overwhelming majority of systems that will not be at risk.

Version 1.1.0

The RFC work has been moved to paseto-standard/paseto-rfc

Fixes:

• #113, #124 - PHP 8 is now supported
• #112 - The code now refers to libsodium constants, not sodium_compat (which are polyfilled anyway)
• #120 - Return an object instead of an array if claims is empty
• #118 - Fixed isValid()

Version 1.0.2

• Bumped minimum sodium_compat version to 1.7.0
• Mostly documentation cleanup