Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/tuupola/branca-php
Authenticated and encrypted API tokens using modern crypto
https://github.com/tuupola/branca-php
api jwt token-authentication xchacha20-poly1305
Last synced: 17 days ago
JSON representation
Authenticated and encrypted API tokens using modern crypto
- Host: GitHub
- URL: https://github.com/tuupola/branca-php
- Owner: tuupola
- License: mit
- Created: 2017-07-19T12:07:54.000Z (over 7 years ago)
- Default Branch: 2.x
- Last Pushed: 2022-05-08T14:42:38.000Z (over 2 years ago)
- Last Synced: 2024-10-11T22:43:55.424Z (about 1 month ago)
- Topics: api, jwt, token-authentication, xchacha20-poly1305
- Language: PHP
- Homepage:
- Size: 71.3 KB
- Stars: 52
- Watchers: 5
- Forks: 7
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Branca Tokens for PHP
Authenticated and encrypted API tokens using modern crypto.
[](https://packagist.org/packages/tuupola/branca)
[](LICENSE)
[](https://github.com/tuupola/branca-php/actions)
[](https://codecov.io/github/tuupola/branca-php)
## What?
[Branca](https://github.com/tuupola/branca-spec) is a secure easy to use token format which makes it hard to shoot yourself in the foot. It uses IETF XChaCha20-Poly1305 AEAD symmetric encryption to create encrypted and tamperproof tokens. Payload itself is an arbitrary sequence of bytes. You can use for example a JSON object, plain text string or even binary data serialized by [MessagePack](http://msgpack.org/) or [Protocol Buffers](https://developers.google.com/protocol-buffers/).
It is possible to use [Branca as an alternative to JWT](https://appelsiini.net/2017/branca-alternative-to-jwt/). There is also an [authentication middleware](https://github.com/tuupola/branca-middleware) for frameworks which support PSR-7 doublepass or PSR-15 standards.
## Install
Install the library using [Composer](https://getcomposer.org/).
``` bash
$ composer require tuupola/branca
```
This branch requires PHP 7.2 or up. The older 1.x branch supports also PHP 5.6, 7.0 and 7.1.
``` bash
$ composer require "tuupola/branca:^1.0"
```
## Usage
Token payload can be any arbitrary data such as string containing an email
address. You also must provide a 32 byte secret key. The key is used for encrypting the payload.
```php
use Branca\Branca;
$key = random_bytes(32);
$branca = new Branca($key);
$payload = "[email protected]";
$token = $branca->encode($payload);
/* hGgg0dPSseaUPZqGloWlDGb2i8hb6iamFBIQaatgYDRhEuaXyByaX0nzmyQk1WYAuSBEMWpB20Z1dENLFItwf1 */
$decoded = $branca->decode($token);
/* [email protected] */
```
Sometimes you might prefer JSON.
```php
use Branca\Branca;
$key = random_bytes(32);
$branca = new Branca($key);
$payload = json_encode(["scope" => ["read", "write", "delete"]]);
$token = $branca->encode($payload);
/*
5R7p5pC1gU5kfVuBUzhl43Ndh4HLT9fxAHrhN1zNRivTuehY8zYYzrVZ8C6d6VcNLfCk3EUgBwwW6kIk0wm32O34OFIYz5LnOIezwcV2Xsfc
*/
$decoded = $branca->decode($token);
$array = json_decode($decoded, true);
/*
Array
(
[scope] => Array
(
[0] => read
[1] => write
[2] => delete
)
)
*/
```
You can keep the token size small by using a space efficient serialization method such as [MessagePack](http://msgpack.org/) or [Protocol Buffers](https://developers.google.com/protocol-buffers/).
```php
use Branca\Branca;
use MessagePack\MessagePack;
use MessagePack\Packer;
use MessagePack\BufferUnpacker;
$key = random_bytes(32);
$branca = new Branca($key);
$payload = (new Packer)->pack(["scope" => ["read", "write", "delete"]]);
$token = $branca->encode($payload);
/*
3iJt0CjqTRh3FGuAf0DHEmhULFIbPVInjguWIkmyCm7RMps5BMJZKa1KwZMN0z58IpPeCxdjoTdkurn9pl0YNrxAQfg3deP0
*/
$decoded = $branca->decode($token);
$unpacked = (new BufferUnpacker($decoded))->unpack();
print_r($unpacked);
/*
Array
(
[scope] => Array
(
[0] => read
[1] => write
[2] => delete
)
)
*/
```
## Timestamp
Branca token includes a timestamp when it was created. When decoding you can optionally pass a `ttl` parameter. Value is passed in seconds. Below example throws en exception if token is older than 60 minutes.
```php
use Branca\Branca;
$key = hex2bin("73757065727365637265746b6579796f7573686f756c646e6f74636f6d6d6974");
$branca = new Branca($key);
$token = "1jJDJOEeG2FutA8g7NAOHK4Mh5RIE8jtbXd63uYbrFDSR06dtQl9o2gZYhBa36nZHXVfiGFz";
print $branca->timestamp($token); /* 123206400 */
try {
$decoded = $branca->decode($token, 3600);
} catch (RuntimeException $exception) {
print $exception->getMessage(); /* Token is expired */
}
```
## Testing
You can run tests either manually or automatically on every code change. Automatic tests require [entr](http://entrproject.org/) to work.
``` bash
$ make test
```
``` bash
$ brew install entr
$ make watch
```
## Contributing
Please see [CONTRIBUTING](CONTRIBUTING.md) for details.
## Security
If you discover any security related issues, please email [email protected] instead of using the issue tracker.
## License
The MIT License (MIT). Please see [License File](LICENSE) for more information.