README

pJWT

PHP implementation of JSON Web Token (JWT). It provides a simple way to create, sign and verify JWT.

The following features are supported:

• Built-in validation for the JWT claims (iat, nbf, exp, jti).
• Symmetric and asymmetric algorithms for protecting integrity:

Requirements

PHP 5.4.0 or above.

Installation

Use composer to install pJWT:

composer require iachilles/pjwt

Code examples

1. Creating JWT

• by using symmetric algorithm HS256:

$claims = ['iat' => time(), 'nbf' => time(), 'exp' => strtotime('+1 day'), 'iss' => 'domain.com', 'uid' => 1];
$headers = ['alg' => 'HS256', 'typ' => 'JWT'];
$jws = new Jws($headers, $claims);
$jws->privateKey = 'YoUr_SeCrEt';
$jws->sign(); //Returns URL-safe string representation of the digitally signed JWT. This encoded JWT can be sent to a user.

• by using asymmetric algorithm RS256:

$claims = ['iat' => time(), 'nbf' => time(), 'exp' => strtotime('+1 day'), 'iss' => 'domain.com', 'uid' => 1];
$headers = ['alg' => 'RS256', 'typ' => 'JWT'];
$jws = new Jws($headers, $claims);
$jws->privateKey = 'file:///path/to/private/key.pem'; //Path to the PEM encoded private key.
$jws->sign(); //Returns URL-safe string representation of the digitally signed JWT. This encoded JWT can be sent to a user.

If the private key is encrypted with a password, you can use the following format:

$jws->privateKey = ['file:///path/to/private/key.pem', 'pAsSwOrd'];

• with protection from replay attacks. In order to protect from replay attacks, you can set 'jti' claim to TRUE during creation JWT.

$claims = ['jti' => true, 'iat' => time(), 'nbf' => time(), 'exp' => strtotime('+1 day')];
$headers = ['alg' => 'RS256', 'typ' => 'JWT'];
$jws = new Jws($headers, $claims);

1. Decoding and verifying JWT

$encodedJwt = 'abcdef.ghijklm.nopqrstuvw'; $jws = Jws::parse($encodedJwt); $jws->getPayload()->issuedAt; //Access to the registered JWT claims $jws->getPayload()->getCustomClaim('user_id'); //Access to the custom claims. $jws->getHeader()->getAlgorithm(); //Access to the JOSE header parameters.

   Verifying signature

   ```php
   $encodedJwt = 'abcdef.ghijklm.nopqrstuvw';
   $jws = Jws::parse($encodedJwt);
   //For symmetric algorithm:
   $jws->privateKey = 'YoUr_SeCrEt';
   //For asymmetric algorithm:
   $jws->certificate = 'file:///path/to/certificate.pem'; //Path to the PEM encoded X.509 certificate.
   $jws->verify(); //TRUE if the signature is valid.

If the signature is valid, you have to validate the JWT claims.

$jws->getPayload()->verify(); //Returns TRUE if the JWT is valid, otherwise it returns a string that contains an error message.

To validate "jti" value you need to create two anonymous functions, and pass them as arguments to the verify method.

$setJti = function($jti)
{
     //Writes "jti" value into storage. (E.g. Redis Db)
};
//This function must return TRUE if the given value exists in storage, false otherwise.
$getJti = function($jti)
{
    //...
};
$jws->getPayload()->verify($setJti, $getJti);