README.md

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.