sop/jwx

A PHP library for JSON web tokens (JWT) with signature (JWS) and encryption (JWE) support.

JWX

A PHP library for JSON web tokens (JWT) with signature (JWS) and encryption (JWE) support.

Also implements unencoded payload option (RFC 7797).

Features

• Signing and signature validation (JWS)
  • HMAC, RSA and EC
• Encryption and decryption with compression and integrity protection (JWE)
  • AES
• Claims validation
  • Configurable with sensible defaults
• JSON Web Keys (JWK)
  • Convert PEM encoded keys to JWK and vice versa

Supported algorithms

• Signature
  • HMAC with SHA-256, SHA-384 and SHA-512
  • RSASSA-PKCS1-v1_5 with SHA-256, SHA-384 and SHA-512
  • ECDSA with P-256, P-384 and P-521 curves
• Content encryption
  • AES-CBC with 128, 192 and 256-bit key sizes
  • AES-GCM with 128, 192 and 256-bit key sizes
• Key management
  • Shared symmetric key (direct)
  • RSAES-PKCS1-v1_5
  • RSAES OAEP
  • AES Key Wrap with 128, 192 and 256-bit key sizes
  • AES-GCM key encryption with 128, 192 and 256-bit key sizes
  • Password-based key encryption (PBES2 with AES Key Wrap)
• Compression
  • DEFLATE

Requirements

• PHP >=7.2
• openssl
• hash
• sop/crypto-types
• sop/crypto-encoding
• sop/aes-kw
• sop/gcm

Installation

This library is available on Packagist.

composer require sop/jwx

Usage

Claims class holds Claim objects that represent the claims. The claims shall be encoded into a JWT which may further be signed or encrypted, producing a JWS or a JWE respectively.

JWS and JWE may also be used to carry arbitrary payload, not just JSON claims.

Code examples

Simple JWT

Parse JWT from https://jwt.io/ HS512 example.

$jwt = new JWT($token);
// create context for the claims validation
// 'your-512-bit-secret' key is used to verify the signature
$ctx = ValidationContext::fromJWK(
    SymmetricKeyJWK::fromKey('your-512-bit-secret'));
// validate claims
$claims = $jwt->claims($ctx);
// print value of the subject claim
echo $claims->subject()->value();

Additional Validation

Parse the same token as above but additionally validate subject and admin claims.

$jwt = new JWT($token);
// validate that the subject is "1234567890"
// validate that the admin claim is true using explicitly provided validator
$ctx = ValidationContext::fromJWK(
    SymmetricKeyJWK::fromKey('your-512-bit-secret'),
        ['sub' => '1234567890']
    )->withConstraint('admin', true, new EqualsValidator());
// validate and print all claims
$claims = $jwt->claims($ctx);
foreach ($claims as $claim) {
    printf("%s: %s\n", $claim->name(), $claim->value());
}

More Examples

See /examples directory for more examples.

• Create a signed JWT
• Consume a signed JWT
• Create an encrypted JWT
• Consume an encrypted JWT
• Create a nested JWT
• Consume a nested JWT
• Encrypt arbitrary data
• Decrypt arbitrary data

License

This project is licensed under the MIT License.

jwx's Issues

Reporting a vulnerability

Hi,

I discovered a vulnerability in JWX that I would like to report. However, I can't seem to find an appropriate (private) channel to contact the maintainer for responsible disclosure.

@sop How would you like to receive this report?

Declaration of JWK X509CertificateChainParameter's constructor must be compatible with JWX ArrayParameterValue's constructor

Hi there, thanks for the great package!

Trying to instantiate a JWK X509CertificateChainParameter throws the following error on PHP v8.0.10:

Declaration of Sop\JWX\JWK\Parameter\X509CertificateChainParameter::__construct(string ...$certs) must be compatible with Sop\JWX\Parameter\Feature\ArrayParameterValue::__construct(...$values)

I wonder if the X509 parameter's constructor definition can be changed to something like:

/**
 * Constructor.
 *
 * @param string[] $certs Base64 encoded DER certificates
 */
public function __construct(...$certs)
{
    /** @var string $cert */
    foreach ($certs as $cert) {
        if (!Base64::isValid($cert)) {
            throw new \UnexpectedValueException(
                'Certificate must be base64 encoded.');
        }
    }
    parent::__construct(self::PARAM_X509_CERTIFICATE_CHAIN, $certs);
}

Happy to open a PR with the change :)