Skip to content

Latest commit

 

History

History
180 lines (129 loc) · 5.14 KB

README.md

File metadata and controls

180 lines (129 loc) · 5.14 KB
Raw

extjwt-cpp

A simple PHP extension for encoding and decoding JSON Web Tokens (JWTs).

Requirements

  • OpenSSL
  • gtest (for jwt-cpp)
  • jwt-cpp package
  • PHP 7 or greater

Note: Only POSIX Operating Systems are currently supported.

Supported Algorithms

  • HS256
  • HS384
  • HS512
  • RS256
  • RS384
  • RS512
  • PS256
  • PS384
  • PS512

Installation

extjwt-cpp requires tools specified in the precursory text. Once said tools are successfully installed on your system, type the following in a console to install extjwt-cpp on your machine.

git clone https://github.com/ace411/extjwt-cpp.git extjwt
cd extjwt
phpize
./configure --enable-extjwt --with-jwtcpp=/path/to/jwtcpp --with-openssl=/path/to/openssl
make && sudo make install

If you intend to run the tests in the tests directory, run the following command:

make test

Do not forget to enable the extension by adding extension=extjwt to your php.ini file.

Usage

Shown below is an example of how to encode and decode a JWT using the default HS256 signature, a payload (claims), and a secret.

const SECRET = '@loki';
const CLAIMS = [
    'iss'       => 'https://github.com/ace411/extjwt-cpp',
    'aud'       => 'https://github.com/ace411/extjwt-cpp',
    'user'      => [
        'github'    => '@ace411',
        'twitter'   => '@agiroLoki'
    ],
    'cpp_ver'   => 11
];

$token = jwt_encode(SECRET, CLAIMS); // outputs a string token

$claims = jwt_decode($token, SECRET); // outputs a PHP hashtable

The supported algorithm constants are:

  • JWT_ALGO_HS256
  • JWT_ALGO_HS384
  • JWT_ALGO_HS512
  • JWT_ALGO_RS256
  • JWT_ALGO_RS384
  • JWT_ALGO_RS512
  • JWT_ALGO_PS256
  • JWT_ALGO_PS384
  • JWT_ALGO_PS512

API

  • jwt_encode
jwt_encode(string $secret, array $claims, int $algorithm)

Description: This function creates a JSON Web Token.

Since:

  • v0.1.0

Argument(s):

  • secret (string) - A discretionary secret key essential for JWT encipherment

For algorithms prefixed with PS and RS, this is the private key

  • claims (array) - The JWT payload; a combination of registered, public, and private claims

  • algorithm (int) - The JWT signature algorithm

Usage:

const RSA_PRIVATE_KEY = <<<'KEY'
-----BEGIN RSA PRIVATE KEY-----
MIICXAIBAAKBgQC8kGa1pSjbSYZVebtTRBLxBz5H4i2p/llLCrEeQhta5kaQu/Rn
vuER4W8oDH3+3iuIYW4VQAzyqFpwuzjkDI+17t5t0tyazyZ8JXw+KgXTxldMPEL9
5+qVhgXvwtihXC1c5oGbRlEDvDF6Sa53rcFVsYJ4ehde/zUxo6UvS7UrBQIDAQAB
AoGAb/MXV46XxCFRxNuB8LyAtmLDgi/xRnTAlMHjSACddwkyKem8//8eZtw9fzxz
bWZ/1/doQOuHBGYZU8aDzzj59FZ78dyzNFoF91hbvZKkg+6wGyd/LrGVEB+Xre0J
Nil0GReM2AHDNZUYRv+HYJPIOrB0CRczLQsgFJ8K6aAD6F0CQQDzbpjYdx10qgK1
cP59UHiHjPZYC0loEsk7s+hUmT3QHerAQJMZWC11Qrn2N+ybwwNblDKv+s5qgMQ5
5tNoQ9IfAkEAxkyffU6ythpg/H0Ixe1I2rd0GbF05biIzO/i77Det3n4YsJVlDck
ZkcvY3SK2iRIL4c9yY6hlIhs+K9wXTtGWwJBAO9Dskl48mO7woPR9uD22jDpNSwe
k90OMepTjzSvlhjbfuPN1IdhqvSJTDychRwn1kIJ7LQZgQ8fVz9OCFZ/6qMCQGOb
qaGwHmUK6xzpUbbacnYrIM6nLSkXgOAwv7XXCojvY614ILTK3iXiLBOxPu5Eu13k
eUz9sHyD6vkgZzjtxXECQAkp4Xerf5TGfQXGXhxIX52yH+N2LtujCdkQZjXAsGdm
B2zNzvrlgRmgBrklMTrMYgm1NPcW+bRLGcwgW2PTvNM=
-----END RSA PRIVATE KEY-----
KEY;

$token = jwt_encode([
    'user'      => 'ace411',
    'twitter'   => '@agiroLoki',
    'iss'       => 'example.org',
    'aud'       => 'example.org',
], RSA_PRIVATE_KEY, JWT_ALGO_RS256);

echo $token;
  • jwt_decode
jwt_decode(string $token, string $secret, int $algorithm)

Description: This function decodes a JSON Web Token into a list of claims.

Since:

  • v0.1.0

Argument(s):

  • token (string) - The JWT to decode

  • secret (string) - A discretionary secret key essential for JWT encipherment

For algorithms prefixed with PS and RS, this is the public key

  • algorithm (int) - The JWT signature algorithm

Usage:

// combine with previous snippet
const RSA_PUBLIC_KEY = <<<'KEY'
-----BEGIN PUBLIC KEY-----
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC8kGa1pSjbSYZVebtTRBLxBz5H
4i2p/llLCrEeQhta5kaQu/RnvuER4W8oDH3+3iuIYW4VQAzyqFpwuzjkDI+17t5t
0tyazyZ8JXw+KgXTxldMPEL95+qVhgXvwtihXC1c5oGbRlEDvDF6Sa53rcFVsYJ4
ehde/zUxo6UvS7UrBQIDAQAB
-----END PUBLIC KEY-----
KEY;

$claims = jwt_decode($token, RSA_PUBLIC_KEY, JWT_ALGO_RS256);

print_r($claims);

Why install extjwt-cpp?

PHP extensions, are by virtue of being C/C++ syntaxes, faster than regular PHP. extjwt is a PHP module which wraps around another C++ library and infuses robustness into the PHP userland. Although it is possible to craft high-quality idiomatic PHP solutions like php-jwt, extjwt is more performant.

Contributing

Consider buying me a coffee if you appreciate the offerings of project.

Buy Me A Coffee