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.

constSECRET = '@loki';
constCLAIMS = [
'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:

constRSA_PRIVATE_KEY = <<<'KEY'-----BEGIN RSA PRIVATE KEY-----MIICXAIBAAKBgQC8kGa1pSjbSYZVebtTRBLxBz5H4i2p/llLCrEeQhta5kaQu/RnvuER4W8oDH3+3iuIYW4VQAzyqFpwuzjkDI+17t5t0tyazyZ8JXw+KgXTxldMPEL95+qVhgXvwtihXC1c5oGbRlEDvDF6Sa53rcFVsYJ4ehde/zUxo6UvS7UrBQIDAQABAoGAb/MXV46XxCFRxNuB8LyAtmLDgi/xRnTAlMHjSACddwkyKem8//8eZtw9fzxzbWZ/1/doQOuHBGYZU8aDzzj59FZ78dyzNFoF91hbvZKkg+6wGyd/LrGVEB+Xre0JNil0GReM2AHDNZUYRv+HYJPIOrB0CRczLQsgFJ8K6aAD6F0CQQDzbpjYdx10qgK1cP59UHiHjPZYC0loEsk7s+hUmT3QHerAQJMZWC11Qrn2N+ybwwNblDKv+s5qgMQ55tNoQ9IfAkEAxkyffU6ythpg/H0Ixe1I2rd0GbF05biIzO/i77Det3n4YsJVlDckZkcvY3SK2iRIL4c9yY6hlIhs+K9wXTtGWwJBAO9Dskl48mO7woPR9uD22jDpNSwek90OMepTjzSvlhjbfuPN1IdhqvSJTDychRwn1kIJ7LQZgQ8fVz9OCFZ/6qMCQGObqaGwHmUK6xzpUbbacnYrIM6nLSkXgOAwv7XXCojvY614ILTK3iXiLBOxPu5Eu13keUz9sHyD6vkgZzjtxXECQAkp4Xerf5TGfQXGXhxIX52yH+N2LtujCdkQZjXAsGdmB2zNzvrlgRmgBrklMTrMYgm1NPcW+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 snippetconstRSA_PUBLIC_KEY = <<<'KEY'-----BEGIN PUBLIC KEY-----MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC8kGa1pSjbSYZVebtTRBLxBz5H4i2p/llLCrEeQhta5kaQu/RnvuER4W8oDH3+3iuIYW4VQAzyqFpwuzjkDI+17t5t0tyazyZ8JXw+KgXTxldMPEL95+qVhgXvwtihXC1c5oGbRlEDvDF6Sa53rcFVsYJ4ehde/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.