kelvinmo/simplejwt

An simple JSON Web Token library for PHP.

SimpleJWT

SimpleJWT is a simple JSON web token library written in PHP., _(*1)

, _(*2)

Features

• JSON web token RFC7519, JSON web signatures RFC7515 and JSON web encryption RFC7516
• JSON web keys RFC7517
• COSE key objects RFC9053
• Signature algorithms
  • HMAC family (HS256, HS384, HS512)
  • RSA family (RS256, RS384, RS512)
  • ECDSA family (ES256, ES384, ES512)
  • EdDSA
• Key management algorithms
  • Key agreement or direct encryption
  • RSAES-PKCS1-v1_5 (RSA1_5)
  • RSAES with OAEP (RSA-OAEP, RSA-OAEP-256)
  • AES key wrap (A128KW, A192KW, A256KW, A128GCMKW, A192GCMKW, A256GCMKW)
  • PBES2 (PBES2-HS256+A128KW, PBES2-HS384+A192KW, PBES2-HS512+A256KW)
  • Elliptic Curve Diffie-Hellman (ECDH-ES), including X25519
• Content encryption algorithms
  • AES_CBC_HMAC_SHA2 family (A128CBC-HS256, A192CBC-HS384, A256CBC-HS512)
  • AES GCM family (A128GCM, A192GCM, A256GCM)

Requirements

• PHP 8.0 or later
• gmp extension
• hash extension
• openssl extension
• sodium extension for EdDSA and X25519 support

Installation

You can install via Composer., _(*3)

composer require kelvinmo/simplejwt

Usage

Key set

Keys used to sign or verify a JWT must firstly be added to a KeySet. You can add keys in the following ways:, _(*4)

1. By loading a JSON object formatted as a JWK Set object as per RFC7517:, _(*5)

   $set = new SimpleJWT\Keys\KeySet();
   $set->load(file_get_contents('private.json'));
   

2. By adding a key manually:, _(*6)

   $set = new SimpleJWT\Keys\KeySet();
   
   // JWK format
   $key = new SimpleJWT\Keys\RSAKey(file_get_contents('jwk.json'), 'json');
   
   // PEM format - note raw key only, no X.509 certificates
   $key = new SimpleJWT\Keys\RSAKey(file_get_contents('rsa.pem'), 'pem');
   
   $set->add($key);
   

3. For a secret used in HMAC signatures, directly:, _(*7)

   $set = SimpleJWT\Keys\KeySet::createFromSecret('secret123');
   
   // The above is a shortcut for the following:
   $set = new SimpleJWT\Keys\KeySet();
   $key = new SimpleJWT\Keys\SymmetricKey('secret123', 'bin');
   $set->add($key);
   

Creating a JWT

To create a JWT, set up the desired headers and claims as separate arrays, then create a JWT object:, _(*8)

// Note $headers['alg'] is required
$headers = ['alg' => 'HS256', 'typ' => 'JWT'];
$claims = ['iss' => 'me', 'exp' => 1234567];
$jwt = new SimpleJWT\JWT($headers, $claims);

The JWT can then be signed and encoded:, _(*9)

try {
    print $jwt->encode($set);
} catch (\RuntimeException $e) {

}

By default, SimpleJWT will automatically include a kid (Key ID) header and a iat (Issued At) claim in all JWTs. If the key used to sign the JWT does not have a kid assigned (e.g. if it is imported from a PEM file), a kid is generated. You can disable this behaviour by specifying $auto_complete to false when calling SimpleJWT\JWT::encode()., _(*10)

Verifying a JWT

To consume and verify a JWT, use the decode function. Note that you will need to supply the expected alg parameter that has been previously agreed out-of-band., _(*11)

try {
    $jwt = SimpleJWT\JWT::decode('abc.def.ghigjghr', $set, 'HS256');
} catch (SimpleJWT\InvalidTokenException $e) {

}

print $jwt->getHeader('alg');
print $jwt->getClaim('sub');

Deserialising a JWT

You can also deserialise a JWT without verifying it using the deserialise function. Note that you should not trust the contents of the data contained in a JWT without verifying them., _(*12)

try {
    $result = SimpleJWT\JWT::deserialise('abc.def.ghigjghr');
} catch (SimpleJWT\InvalidTokenException $e) {

}

print $result['claims']['sub'];
print $result['signatures'][0]['headers']['alg'];
print $result['signatures'][0]['signing_input'];  // abc.def
print $result['signatures'][0]['signature'];      // ghigjghr
// Additional indices under $result['signatures'] if the JWT has more than
// one signature

Creating a JWE

To create a JWE, set up the desired header array and plaintext, then create a JWE object:, _(*13)

// Note $headers['alg'] and $headers['enc'] are required
$headers = ['alg' => 'PBES2-HS256+A128KW', 'enc' => 'A128CBC-HS256'];
$plaintext = 'This is the plaintext I want to encrypt.';
$jwt = new SimpleJWT\JWE($headers, $plaintext);

The JWE can then be encrypted:, _(*14)

try {
    print $jwt->encrypt($set);
} catch (\RuntimeException $e) {

}

Decrypting a JWE

To decrypt a JWE, use the decrypt function:, _(*15)

try {
    $jwt = SimpleJWT\JWE::decrypt('abc.def.ghi.klm.nop', $set, 'PBES2-HS256+A128KW');
} catch (SimpleJWT\InvalidTokenException $e) {

}

print $jwt->getHeader('alg');
print $jwt->getPlaintext();

Licence

BSD 3 clause, _(*16)