Download the PHP package timjmasters/php-jws without Composer

php-jws

Some JWS Tools for PHP - authored by Timothy John Masters

This code was written more as a learning/practice exercise, the firebase/php-jwt is likely to be much more complete and feature rich.

Currently only supports JWS compact serialization with no intention of implementing a JWS JSON serialization solution.

Installation

Install as a dependency using composer, then use the composer autoloader: composer require timjmasters/php-jws

Usage

Use the JWSUtil class to create and verify JWS tokens.

JWSUtil - utility class for creating and verifying JWS objects

• JWSUtil::createFromPayload($payload, array $options) : JWS Creates a JWS object using the specified payload and options, including encoding the parts and signing the token:
  • header: set any header fields you need, defaults to ["alg" => "HS256", "typ" => "JWT"] see below for supported algorithms
  • payload: an array of options regarding the payload:
    • encoding: either json_encoding or as_string (default: json_encoding) If 'json_encoding' is used, the payload will be JSON encoded before being set on the object, so the object's getPayload() method will return a JSON encoded string unless the json_decode argument is supplied. If 'as_string' is used the payload will be cast to a string before being set on the object.
    • encoding_options: Options to pass to the json_encode function if used eg JSON_PRETTY_PRINT (default: 0)
  • secret: a secret or key to use for creating the signature
• JWSUtil::createFromEncoded(string $token, bool $json_decode) : JWS Creates a JWS object from an encoded JWS string, if the $json_decode argument is true, the payload will be decoded before being set, an exception will be thrown if the payload cannot be decoded. The signature is set as supplied, so make sure you verify the token before you trust it.
• JWSUtil::verify(JWS $jws, $secret, array $allowed_algorithms) Verify that a JWS token's signature matches it's contents. Returns false if the token signature isn't verified.
  • The header's algorithm isn't in the supplied allowed algorithms (default: ["HS256", "RS256"])
  • If HMAC:
    • The base64url encoded json encoded header concatenated with a single period and the base64url encoded payload (optionally json encoded when the token was created) is hashed using the secret provided and the result is compared to the token's signature
  • If RSA:
    • The openssl_verify function is used to verify that the token's signature is valid for the base64url encoded json encoded header concatenated with a single period and the base64url encoded payload (optionally json encoded when the token is created)
    • The public key should be provided in the $secret parameter, it can be a string or a resource identifier created using an openssl function.

JWS

The object has methods for viewing data encoded in the token. It's not recommended you use the setters directly, rather create tokens using the JWSUtil class.

• $jws->getHeader()
  • Get the header as an array typically something like ['alg' => 'RS256', 'typ' => 'JWT']
• $jws->getPayload($json_decode = false)
  • Get the payload, the optional json_decode parameter is a convenience in case the payload wasn't encoded during token creation ie. using the 'as_string' encoding option but is still valid json which you'd like decoded.
  • The payload doesn't necessarily need to be a json string or array, it could be binary data
• $jws->getSignature()
  • Get the unencoded signature, usually a hash or binary string
• $jws->getHeaderEncoded()
  • Get the JWS header as a base64url encoded json encoded string
• $jws->getPayloadEncoded()
  • Get the payload base64url encoded
  • The payload can optionally be encoded when set
• $jws->getSignatureEncoded()
  • Get the signature base64url encoded
• $jws->getEncoded()
  • Get all the encoded parts concatenated with periods between. eg eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.WUphQgEfGvtdUCw4UntIh__bemKY6eDFjX2K2XCZP
  • Equivalent to $jws->getHeaderEncoded() . '.' . $jws->getPayloadEncoded() . '.' . $jws->getSignatureEncoded
• $jws->setHeader(array $header)
  • Set the JWS header
  • The encoded value will be updated and the signature won't match if the header has changed
• $jws->setPayload($payload, $json_encode = false)
  • Set the payload, optionally encode it as a json string
  • The encoded value will be updated and the signature won't match if the payload has changed
• $jws->setSignature($signature)
  • Set the signature
  • Not checked against the header and payload, not recommended you use this directly

Notes

Currently supported algorithms

• HS256
  • HMAC SHA 256 - JWS tokens will be signed using the secret option
• RS256
  • RSA SHA 256 - JWS tokens will be signed assuming the secret option is a private key

Examples

Create a JWS object from an array, json encode it

Create a JWS object using RS256

Verify a token from Google