Paseto Laravel Package

This is mostly just a maintenance release that bumps some dependencies.

Though, a new dependency was added (symfony/polyfill-php83) and some of the existing dependencies had minor version bumps.

What's Changed

• Routine maintenance by @paragonie-security in https://github.com/paragonie/paseto/pull/178

Full Changelog: https://github.com/paragonie/paseto/compare/v3.4.0...v3.5.0

What's Changed

• Constant-time alternative to strtok() by @paragonie-security in https://github.com/paragonie/paseto/pull/176

Full Changelog: https://github.com/paragonie/paseto/compare/v3.3.0...v3.4.0

Version 3.3.0 has been deleted as it was accidentally tagged early.

Include updated test vector

Updated minimum version of paragonie/easy-ecc to 1.1.0.

Updated minimum version of paragonie/easy-ecc to 1.1.0.

What's Changed

• importPem by @frederikbosch in https://github.com/paragonie/paseto/pull/169
• Upgrade Test Dependencies (Psalm, PHPUnit) by @paragonie-security in https://github.com/paragonie/paseto/pull/171
• Update sodium_compat dependency to allow v2.0 by @paragonie-security in https://github.com/paragonie/paseto/pull/174
  • More information

Full Changelog: https://github.com/paragonie/paseto/compare/v3.1.1...v3.2.0

• Fixed #170

What's Changed

• Add pronunciation key to README by @cab in https://github.com/paragonie/paseto/pull/158
• Error if symmetric key length is incorrect by @aidantwoods in https://github.com/paragonie/paseto/pull/161
• Enforce EdDSA key runtime checks before sign() for PASETO v4 by @paragonie-security in https://github.com/paragonie/paseto/pull/164
• Simple has method since get throws Exception by @oojacoboo in https://github.com/paragonie/paseto/pull/165
• [Version 3] Fix creating token from encoded private key by @frederikbosch in https://github.com/paragonie/paseto/pull/166
• Move all encoding and decoding of asymmetric keys to specific version files by @frederikbosch in https://github.com/paragonie/paseto/pull/168

New Contributors

• @cab made their first contribution in https://github.com/paragonie/paseto/pull/158
• @oojacoboo made their first contribution in https://github.com/paragonie/paseto/pull/165
• @frederikbosch made their first contribution in https://github.com/paragonie/paseto/pull/166

Full Changelog: https://github.com/paragonie/paseto/compare/v3.0.2...v3.1.0

• AsymmetricSecretKey now validates that the public key is correct for a given Ed25519 seed.

• AsymmetricSecretKey now validates that the public key is correct for a given Ed25519 seed.

• Invalid base64 encoding of PASETO tokens is rejected. See https://github.com/paseto-standard/paseto-spec/issues/28 for the specification discussion.

• Removed Version1 and Version 2 (which were deprecated earlier this year).
• Minimum PHP Version: 8.1.0
• Removed HKDF polyfill
• Removed __toString() weirdness for PHP < 7.4
• Lots of code clean-up; making use of the updated type system in PHP 8.1
• Use Corner for more helpful exceptions.
• Removed all hacks and annotations to make Psalm happy. Our code is now fully statically analyzed on every CI/CD push.

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

• #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.

• #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.

• 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!)

• 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

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

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

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.

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()

• Bumped minimum sodium_compat version to 1.7.0
• Mostly documentation cleanup

• Fix #74, which rendered a unit test useless (and the test in question was failing).

It turns out, we don't need permission from the IETF to use PASETO in the real world (i.e. OAuth2). This is fortunate, because it's unlikely for them to accept a JWT alternative in the first place, no matter how doomed their christened standard may be.

Based on the feedback we've already received from security and cryptography experts around the world, this is simple and usable enough to use in the real world. So there's no point in delaying a stable release any further.

The documentation and reference implementation has been updated with some feedback from the RFC review process (i.e. optional footer handling).

Protocol changes:

None. We're quite happy with the way Paseto is currently designed.

PHP Library Changes:

• If you pass a footer to the third argument, it will be evaluated with strict constant-time equality. Otherwise, it will strip it off the token and decoded from base64.

Documentation Changes:

• Handling optional footers is less strict, as per RFC draft feedback.

We've completed draft-00 of our proposed RFC. This makes us one step closer to tagging v1.0.0.

Protocol changes:

None. We're quite happy with the way Paseto is currently designed.

PHP Library Changes:

• Use setSignatureMode() instead of setEncryptionMode() for Version1. The end result was the same, but it's important to be explicit about our intent in our implementation.

Protocol changes:

None. We're quite happy with the way Paseto is currently designed.

PHP Library Changes:

• A lot of mostly-internal type-safety work done by @aidantwoods
  • Fixed: A footer of 0 would not append to the token due to PHP's treatment of falsy values.
• We explicitly tell phpseclib to use e = 65537 for version 1.

Other Changes:

• A lot of documentation has been fleshed out. Give it a read here: https://github.com/paragonie/paseto/tree/master/docs
• Several people have begun developing PASETO implementations in other programming languages. See all of them here.

Special thanks to @aidantwoods for contributing a lot to this minor release.

Protocol changes:

None. We're quite happy with the way Paseto is currently designed.

PHP Library Changes:

• JsonToken building was split out into a separate Builder class, to make key management easier to reason about.
• Instead of a string constant containing a header, the version object itself is expected in a few places.
• Purpose is now passed as an object rather than a string.

Biggest change: We've changed our name from PAST to Paseto. It should be easier to find in a Google search.

Other fixes since v0.3.0:

• The HKDF constants have been updated to reflect the name change, and our test vectors use a full ISO 8601 DateTime string (including timezone).
• #26 was fixed with our reference implementation.

This may be our last pre-1.0.0 release. The only thing left to do (barring the discovery of any cryptography flaws unique to Paseto) is documentation work, including drafting an RFC to submit to the IETF.

A lot has changed since v0.2.0! PAST is now a lot faster, simpler, and has a greater degree of misuse resistance.

• seal has been removed.
• auth has been removed.
• enc has been renamed to local.
• sign has been renamed to public.
• We now use unpadded base64url encoding.
• For encryption, nonces are now derived from the plaintext in addition to the OS CSPRNG, using HMAC-SHA384 (version 1) or keyed BLAKE2b (version 2). This should mitigate the risk of nonce reuse on systems or programming languages with insecure RNGs.
• More unit tests.
• More documentation. It should now be straightforward to implement PAST in other languages.

PAST now has a basic reference implementation and a first draft for the specification.

Notable change to the cryptography since v0.1.0: We now feed data into MACs and signature algorithms in such a way to minimize the risk of canonicalization attacks. Although no practical exploits are known for HMAC-SHA384 or Poly1305, simply concatenating different values together as one giant string seems like a needlessly cavalier design decision. Our new serialization format should effectively mitigate any risks.

We're going to take some time to accept feedback from the community, polish up the documentation, and request review from professional cryptographers.

Unless a game-over protocol flaw is discovered, the current implementation should be assumed stable enough to serve as a reference point for developing implementations in other programming languages. However, don't deploy this in production until v1.0.0 has been tagged and released.