README

A simple and extensible PHP implementation of JWS based on JWS draft](http://tools.ietf.org/html/draft-ietf-jose-json-web-signature).

Note

gamegos/jwt library is more suitable for a JSON WEB TOKEN(JWT) solution

Installation

The recommended way to install gamegos/jws is through Composer.

{
    "require": {
        "gamegos/jws": "~1.0"
    }
}

Basic Usage

Encoding

$headers = array(
    'alg' => 'HS256', //alg is required. see *Algorithms* section for supported algorithms
    'typ' => 'JWT'
);

// anything that json serializable
$payload = array(
    'sub' => 'someone@example.com',
    'iat' => '1402993531'
);

$key = 'some-secret-for-hmac';

$jws = new \Gamegos\JWS\JWS();
echo $jws->encode($headers, $payload, $key);
//eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJzb21lb25lQGV4YW1wbGUuY29tIiwiaWF0IjoiMTQwMjk5MzUzMSJ9.0lgcQRnj_Jour8MLdIc71hPjjLVcQAOtagKVD9soaqU

Decoding & Verifying

$key = 'some-secret-for-hmac';

//jws encoded string
$jwsString = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJzb21lb25lQGV4YW1wbGUuY29tIiwiaWF0IjoiMTQwMjk5MzUzMSJ9.0lgcQRnj_Jour8MLdIc71hPjjLVcQAOtagKVD9soaqU';

$jws = new \Gamegos\JWS\JWS();

$jws->verify($jwsString, $key);

If everything is ok you will get an array with 'headers' and 'payload'.

/*
Array
(
    [headers] => Array
        (
            [alg] => HS256
            [typ] => JWT
        )

    [payload] => Array
        (
            [sub] => someone@example.com
            [iat] => 1402993531
        )

)
*/

You will get one of these exceptions if something bad happens.

If you only want to parse jws string without signature verification you can use decode method.

$jws->decode($jwsString);

Supported Algorithms

Currently these algorithms are supported.

See JWA Cryptographic Algorithms for Digital Signatures and MACs page for full list of defined algorithms for JWS.

Exceptions

InvalidSignatureException
MalformedSignatureException
UnspecifiedAlgorithmException
UnsupportedAlgorithmException

Extending: Adding New Signature/MAC Algorithm

Create an algorithm class that implements \Gamegos\JWS\Algorithm\AlgorithmInterface.

//example NoneAlgorithm
class NoneAlgorithm implements \Gamegos\JWS\Algorithm\AlgorithmInterface
{

    public function sign($key, $data)
    {
        return '';
    }

    public function verify($key, $data, $signature)
    {
        return (string) $signature === '';
    }
}

//...
$jws = new \Gamegos\JWS\JWS();
$jws->registerAlgorithm('my-new-algorithm', new NoneAlgorithm());

Now you can use my-new-algorithm as a usual 'alg' parameter.

Known Limitations

JWS JSON Serialization is not supported.

¹ requires php openssl module.

gamegos / jws

Maintainers

Details