README

使用现代加密技术的认证和加密API令牌。

是什么？

Branca 是一种安全的、易于使用的令牌格式，可以防止用户犯错。它使用 IETF XChaCha20-Poly1305 AEAD 对称加密来创建加密和防篡改的令牌。有效载荷本身是一个任意字节序列。例如，您可以使用 JSON 对象、纯文本字符串，甚至通过 MessagePack 或 Protocol Buffers 序列化的二进制数据。

可以将 Branca 作为 JWT 的替代品 使用。还有适用于支持 PSR-7 双遍历或 PSR-15 标准的框架的 认证中间件。

安装

使用 Composer 安装库。

$ composer require tuupola/branca

此分支需要 PHP 7.2 或更高版本。较老的 1.x 分支还支持 PHP 5.6、7.0 和 7.1。

$ composer require "tuupola/branca:^1.0"

使用方法

令牌有效载荷可以是任何任意数据，例如包含电子邮件地址的字符串。您还必须提供一个 32 字节的密钥。密钥用于加密有效载荷。

use Branca\Branca;

$key = random_bytes(32);
$branca = new Branca($key);

$payload = "tuupola@appelsiini.net";
$token = $branca->encode($payload);
/* hGgg0dPSseaUPZqGloWlDGb2i8hb6iamFBIQaatgYDRhEuaXyByaX0nzmyQk1WYAuSBEMWpB20Z1dENLFItwf1 */

$decoded = $branca->decode($token);
/* tuupola@appelsiini.net */

有时您可能更喜欢 JSON。

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
        )

)
*/

您可以通过使用诸如 MessagePack 或 Protocol Buffers 之类的空间高效序列化方法来保持令牌大小小。

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
        )

)
*/

时间戳

Branca 令牌包括创建时的时间戳。解码时，您可以可选地传递一个 ttl 参数。值以秒为单位。以下示例在令牌超过 60 分钟时抛出异常。

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 */
}

测试

您可以通过手动或自动在每次代码更改时运行测试来运行测试。自动测试需要 entr 工作。

$ make test

$ brew install entr
$ make watch

贡献

请参阅 CONTRIBUTING 获取详细信息。

安全性

如果您发现任何与安全相关的问题，请通过电子邮件 tuupola@appelsiini.net 而不是使用问题跟踪器。

许可

MIT 许可证 (MIT)。有关更多信息，请参阅 许可文件。