Documentation

JWT
in package

JSON Web Token implementation, based on this spec: https://tools.ietf.org/html/rfc7519

PHP version 5

Tags
category

Authentication

author

Neuman Vong neuman@twilio.com

author

Anant Narayanan anant@php.net

license

http://opensource.org/licenses/BSD-3-Clause 3-clause BSD

link
https://github.com/firebase/php-jwt

Table of Contents

ASN1_BIT_STRING  = 0x3
ASN1_INTEGER  = 0x2
ASN1_SEQUENCE  = 0x10
$leeway  : int
When checking nbf, iat or expiration times, we want to provide some extra leeway time to account for clock skew.
$supported_algs  : array<string, array<string|int, string>>
$timestamp  : int|null
Allow the current timestamp to be specified.
constantTimeEquals()  : bool
decode()  : stdClass
Decodes a JWT string into a PHP object.
encode()  : string
Converts and signs a PHP object or array into a JWT string.
jsonDecode()  : mixed
Decode a JSON string into a PHP object.
jsonEncode()  : string
Encode a PHP array into a JSON string.
sign()  : string
Sign a string with a given key and algorithm.
urlsafeB64Decode()  : string
Decode a string with URL-safe Base64.
urlsafeB64Encode()  : string
Encode a string with URL-safe Base64.
encodeDER()  : string
Encodes a value into a DER object.
getKey()  : Key
Determine if an algorithm has been provided for each Key
handleJsonError()  : void
Helper method to create a JSON error.
readDER()  : array<string|int, mixed>
Reads binary DER-encoded data and decodes into a single object
safeStrlen()  : int
Get the number of bytes in cryptographic strings.
signatureFromDER()  : string
Encodes signature from a DER object.
signatureToDER()  : string
Convert an ECDSA signature to an ASN.1 DER sequence
verify()  : bool
Verify a signature with the message, key and method. Not all methods are symmetric, so we must have a separate verify and sign method.

Constants

ASN1_BIT_STRING

private mixed ASN1_BIT_STRING = 0x3

ASN1_INTEGER

private mixed ASN1_INTEGER = 0x2

ASN1_SEQUENCE

private mixed ASN1_SEQUENCE = 0x10

Properties

$leeway

When checking nbf, iat or expiration times, we want to provide some extra leeway time to account for clock skew.

public static int $leeway = 0

$supported_algs

public static array<string, array<string|int, string>> $supported_algs = ['ES384' => ['openssl', 'SHA384'], 'ES256' => ['openssl', 'SHA256'], 'HS256' => ['hash_hmac', 'SHA256'], 'HS384' => ['hash_hmac', 'SHA384'], 'HS512' => ['hash_hmac', 'SHA512'], 'RS256' => ['openssl', 'SHA256'], 'RS384' => ['openssl', 'SHA384'], 'RS512' => ['openssl', 'SHA512'], 'EdDSA' => ['sodium_crypto', 'EdDSA']]

$timestamp

Allow the current timestamp to be specified.

public static int|null $timestamp = null

Useful for fixing a value within unit testing. Will default to PHP time() value if null.

Methods

constantTimeEquals()

public static constantTimeEquals(string $left, string $right) : bool
Parameters
$left : string

The string of known length to compare against

$right : string

The user-supplied string

Return values
bool —

decode()

Decodes a JWT string into a PHP object.

public static decode(string $jwt, Key|array<string, Key> $keyOrKeyArray) : stdClass
Parameters
$jwt : string

The JWT

$keyOrKeyArray : Key|array<string, Key>

The Key or associative array of key IDs (kid) to Key objects. If the algorithm used is asymmetric, this is the public key Each Key object contains an algorithm and matching key. Supported algorithms are 'ES384','ES256', 'HS256', 'HS384', 'HS512', 'RS256', 'RS384', and 'RS512'

Tags
throws
InvalidArgumentException

Provided key/key-array was empty

throws
DomainException

Provided JWT is malformed

throws
UnexpectedValueException

Provided JWT was invalid

throws
SignatureInvalidException

Provided JWT was invalid because the signature verification failed

throws
BeforeValidException

Provided JWT is trying to be used before it's eligible as defined by 'nbf'

throws
BeforeValidException

Provided JWT is trying to be used before it's been created as defined by 'iat'

throws
ExpiredException

Provided JWT has since expired, as defined by the 'exp' claim

uses
jsonDecode
uses
urlsafeB64Decode
Return values
stdClass —

The JWT's payload as a PHP object

encode()

Converts and signs a PHP object or array into a JWT string.

public static encode(array<string|int, mixed> $payload, string|resource|OpenSSLAsymmetricKey|OpenSSLCertificate $key, string $alg[, string $keyId = null ][, array<string, string> $head = null ]) : string
Parameters
$payload : array<string|int, mixed>

PHP array

$key : string|resource|OpenSSLAsymmetricKey|OpenSSLCertificate

The secret key.

$alg : string

Supported algorithms are 'ES384','ES256', 'HS256', 'HS384', 'HS512', 'RS256', 'RS384', and 'RS512'

$keyId : string = null
$head : array<string, string> = null

An array with header elements to attach

Tags
uses
jsonEncode
uses
urlsafeB64Encode
Return values
string —

A signed JWT

jsonDecode()

Decode a JSON string into a PHP object.

public static jsonDecode(string $input) : mixed
Parameters
$input : string

JSON string

Tags
throws
DomainException

Provided string was invalid JSON

Return values
mixed —

The decoded JSON string

jsonEncode()

Encode a PHP array into a JSON string.

public static jsonEncode(array<string|int, mixed> $input) : string
Parameters
$input : array<string|int, mixed>

A PHP array

Tags
throws
DomainException

Provided object could not be encoded to valid JSON

Return values
string —

JSON representation of the PHP array

sign()

Sign a string with a given key and algorithm.

public static sign(string $msg, string|resource|OpenSSLAsymmetricKey|OpenSSLCertificate $key, string $alg) : string
Parameters
$msg : string

The message to sign

$key : string|resource|OpenSSLAsymmetricKey|OpenSSLCertificate

The secret key.

$alg : string

Supported algorithms are 'ES384','ES256', 'HS256', 'HS384', 'HS512', 'RS256', 'RS384', and 'RS512'

Tags
throws
DomainException

Unsupported algorithm or bad key was specified

Return values
string —

An encrypted message

urlsafeB64Decode()

Decode a string with URL-safe Base64.

public static urlsafeB64Decode(string $input) : string
Parameters
$input : string

A Base64 encoded string

Tags
throws
InvalidArgumentException

invalid base64 characters

Return values
string —

A decoded string

urlsafeB64Encode()

Encode a string with URL-safe Base64.

public static urlsafeB64Encode(string $input) : string
Parameters
$input : string

The string you want encoded

Return values
string —

The base64 encode of what you passed in

encodeDER()

Encodes a value into a DER object.

private static encodeDER(int $type, string $value) : string
Parameters
$type : int

DER tag

$value : string

the value to encode

Return values
string —

the encoded object

getKey()

Determine if an algorithm has been provided for each Key

private static getKey(Key|ArrayAccess<string, Key>|array<string, Key> $keyOrKeyArray, string|null $kid) : Key
Parameters
$keyOrKeyArray : Key|ArrayAccess<string, Key>|array<string, Key>
$kid : string|null
Tags
throws
UnexpectedValueException
Return values
Key —

handleJsonError()

Helper method to create a JSON error.

private static handleJsonError(int $errno) : void
Parameters
$errno : int

An error number from json_last_error()

Tags
throws
DomainException
Return values
void —

readDER()

Reads binary DER-encoded data and decodes into a single object

private static readDER(string $der, int $offset) : array<string|int, mixed>
Parameters
$der : string

the binary data in DER format

$offset : int

the offset of the data stream containing the object to decode

Return values
array<string|int, mixed> —

safeStrlen()

Get the number of bytes in cryptographic strings.

private static safeStrlen(string $str) : int
Parameters
$str : string
Return values
int —

signatureFromDER()

Encodes signature from a DER object.

private static signatureFromDER(string $der, int $keySize) : string
Parameters
$der : string

binary signature in DER format

$keySize : int

the number of bits in the key

Return values
string —

the signature

signatureToDER()

Convert an ECDSA signature to an ASN.1 DER sequence

private static signatureToDER(string $sig) : string
Parameters
$sig : string

The ECDSA signature to convert

Return values
string —

The encoded DER object

verify()

Verify a signature with the message, key and method. Not all methods are symmetric, so we must have a separate verify and sign method.

private static verify(string $msg, string $signature, string|resource|OpenSSLAsymmetricKey|OpenSSLCertificate $keyMaterial, string $alg) : bool
Parameters
$msg : string

The original message (header and body)

$signature : string

The original signature

$keyMaterial : string|resource|OpenSSLAsymmetricKey|OpenSSLCertificate

For HS*, a string key works. for RS*, must be an instance of OpenSSLAsymmetricKey

$alg : string

The algorithm

Tags
throws
DomainException

Invalid Algorithm, bad key, or OpenSSL failure

Return values
bool —

Search results