FastSitePHP\Security\Crypto\JWT

JSON Web Tokens (JWT)

Código Fonte

Links Relacionados

• https://jwt.io/
• https://tools.ietf.org/html/rfc7519
• https://en.wikipedia.org/wiki/JSON_Web_Token
• http://self-issued.info/docs/draft-ietf-oauth-json-web-token.html

Código de Exemplo

// A carga do JWT pode ser um Objeto ou um Array (Dicionário).
$payload = [
    'User' => 'John Doe',
    'Roles' => ['Admin', 'SQL Editor']
];

// Gere um Chave para Codificação (Assinando).
// A chave é uma longa string hexadecimal de bytes aleatórios seguros.
// A chave seria tipicamente salva com seu app ou nas configurações.
$jwt = new \FastSitePHP\Security\Crypto\JWT();
$key = $jwt->generateKey();

// Codifique e Decodifique o JWT com a Classe Auxiliar Crypto e Definições
// de Configuração.
// Ao utilizar os parâmetros padrão com ao classe auxiliar, os dados tem
// validade de uma hora.
$app->config['JWT_KEY'] = $key;
$token = \FastSitePHP\Security\Crypto::encodeJWT($payload);
$data  = \FastSitePHP\Security\Crypto::decodeJWT($token);

// Codifique (Assine) e Decodifique (Verifique) utilizando a classe JWT. Ao
// utilizar as definições padrão com a classe JWT, nenhuma expiração é
// especificada, todas as reivindicações são validadas e uma chave é
// necessária.
$token = $jwt->encode($payload, $key);
$data  = $jwt->decode($token, $key);

// Adicione Reivindicações à Carga Válida e utilize uma Chave Insegura para
// Compatibilidade com ouros sits (Geralmente demonstrações online de JWT
// são mostradas utilizando senhas simples para a chave). Por padrão, chaves
// necessitam ser seguras, com comprimento apropriado e no formato Base64 ou
// Hexadecimal.

$payload = $jwt->addClaim($payload, 'exp', '+10 minutes');
$payload = $jwt->addClaim($payload, 'iss', 'example.com');

$jwt
    ->useInsecureKey(true)
    ->allowedIssuers(['example.com']);

$insecure_key = 'password123';
$token = $jwt->encode($payload, $insecure_key);
$data  = $jwt->decode($token, $insecure_key);

// A carga do JWT pode ser um Objeto ou um Array (Dicionário)
$payload = new \stdClass;
$payload->User = 'John Doe';
$payload->Roles = ['Admin', 'SQL Editor'];

// Crie uma Classe JWT, especifique o Algorítmo 'RS256 e gere um Par de Chaves
$jwt = new \FastSitePHP\Security\Crypto\JWT();
$jwt
    ->algo('RS256')
    ->allowedAlgos(['RS256']);

list($private_key, $public_key) = $jwt->generateKey();

// Encode (Sign) and Decode (Verify)
$token = $jwt->encode($payload, $private_key);
$data  = $jwt->decode($token, $public_key);

Métodos

__construct()

Class Constructor

If using PHP 5.5 or below then [hash_equals()] is polyfilled, and [bin2hex()] and [hex2bin()] are polyfilled for PHP 5.3.

generateKey($key_type = 'base64')

Generate a secure key based on the algorithm specified from the function [algo()]. When using HMAC the key is returned in either Base64 of Hex format depending on the $type parameter (defaults to Base64); and when using RSA an array is returned in the format of [private_key, public_key].

Retorna: string | array

encode($payload, $key)

Encode and Create a JWT. The algorithm to use can be specified from the function [algo()]. By default a secure key is required and one can be generated from the function [generateKey()]. If a weak key is required for compatibility with other code see the function [useInsecureKey()].

Retorna: string - JSON Web Token (JWT)

decode($token, $key)

Decode and Verify a JWT. If the token is not valid null will be returned unless [exceptionOnError(true)] is set and then an exception will be thrown.

Unless settings are changed from [allowedAlgos()] only the default algorithm 'HS256' is accepted for decoding.

If the payload has a claim defined then it will be validated by default. This can be turned off by calling [validateDefinedClaims(false)].

To require and validate specific claims use the [require*()/allowed*()] getter/setter functions of this class.

Retorna: array - The payload that was originally encoded.

addClaim($payload, $claim, $value)

Helper function to add a JWT field value to either an array or object. Use this prior to calling [encode()]. Time fields ['exp', 'nbf', 'iat'] must be either an integer representing a Unix Timestamp or a string that is valid for the PHP function [strtotime()].

Example to expire a Token after 10 minutes:
    $payload = $jwt->addClaim($payload, 'exp', '+10 minutes');

Retorna: array | object - The modified payload

exceptionOnError($value = null)

By default [decode()] returns null when a JWT cannot be validated or invalid settings are used. When the value of this function is set to [true] then an exception will be thrown instead.

Retorna: bool | $this

algo($new_value = null)

Get or set the default JWT Algorithm to use, for supported algorithms see comments in [allowedAlgos()]. Defaults to 'HMAC' with 'SHA256'.

Retorna: string | $this

allowedAlgos(array $new_value = null)

Get or set an array of allowed JWT Algorithms to accept when decoding.

HMAC [HS256, HS384, HS512] and RSA [RS256, RS384, RS512] are supported. Elliptic Curve Digital Signature Algorithms (ECDSA) [ES256, ES384, ES512] are not supported by this class because PHP's OpenSSL implementation does not provide built-in support.

If need to use (ECDSA) with PHP there are several options:
  Encode/Decode Fast (PHP C Extension):
    https://github.com/cdoco/php-jwt
  Encode/Decode Slower (Using PHP Code):
    https://github.com/lcobucci/jwt
    https://github.com/web-token/jwt-framework

Retorna: array | $this

useInsecureKey($new_value = null)

Get or set Key Requirement when using and HMAC JWT [HS256, HS384, HS512]. Defaults to [false] and with default settings a strong key size must be used.

This should only be set to [true] if compatibility with other code is needed. Often online samples use common passwords such as 'secret' when signing JWT's which is why this setting was created.

Retorna: bool | $this

validateDefinedClaims($new_value = null)

Get or set whether defined claims must be validated when [decode()] is called. Defaults to true.

Example if the payload has a value for [exp] then by default the JWT Expiration Time is checked otherwise [requireExpireTime()] would have to be set.

Retorna: bool | $this

allowedIssuers(array $new_value = null)

Get or set an allowed list of values for "iss" (Issuer) Claim

Retorna: array | null | $this

• https://tools.ietf.org/html/rfc7519#section-4.1.1

requireSubject($new_value = null)

Get or set validation for the "sub" (Subject) Claim

Retorna: string | null | $this

• https://tools.ietf.org/html/rfc7519#section-4.1.2

allowedAudiences(array $new_value = null)

Get or set an allowed list of audience values for the "aud" (Audience) Claim

Retorna: array | null | $this

• https://tools.ietf.org/html/rfc7519#section-4.1.3

requireExpireTime($new_expiration_time = null, $leeway = null)

Get or set validation for the "exp" (Expiration Time) Claim

Retorna: array | $this

• https://tools.ietf.org/html/rfc7519#section-4.1.4

requireNotBefore($new_not_before_time = null, $leeway = null)

Get or set validation for the "nbf" (Not Before) Claim

Retorna: array | $this

• https://tools.ietf.org/html/rfc7519#section-4.1.5

requireIssuedAt($new_value = null)

Get or set validation for the "iat" (Issued At) Claim

Retorna: bool | $this

• https://tools.ietf.org/html/rfc7519#section-4.1.6

requireJwtId($new_value = null)

Get or set validation for the "jti" (JWT ID) Claim

Retorna: bool | $this

• https://tools.ietf.org/html/rfc7519#section-4.1.7