深入理解paragonie/paseto：PHP版PASETO令牌使用指南

深入理解paragonie/paseto：PHP版PASETO令牌使用指南

paseto Platform-Agnostic Security Tokens 项目地址: https://gitcode.com/gh_mirrors/pa/paseto

什么是PASETO？

PASETO（Platform-Agnostic SEcurity TOkens）是一种现代化的安全令牌标准，旨在解决JWT（JSON Web Tokens）中存在的一些安全问题。paragonie/paseto是PASETO协议的PHP实现，提供了简单易用且类型安全的API来创建和验证安全令牌。

核心概念

密钥管理

paragonie/paseto采用严格的类型安全设计，将不同类型的密钥封装在特定对象中：

1. 对称密钥：用于本地（local）用途，同时用于签名和验证
2. 非对称密钥：
   • 签名密钥：用于签名（sign）
   • 验证密钥：用于验证（verify）

use ParagonIE\Paseto\Keys\{AsymmetricSecretKey, SymmetricKey};

// 生成非对称密钥对
$signingKey = new AsymmetricSecretKey(sodium_crypto_sign_keypair());
$verificationKey = $signingKey->getPublicKey();

// 生成对称密钥
$sharedKey = new SymmetricKey(random_bytes(32));

密钥存储与传输

编码/解码密钥

// 编码密钥
$signingKeyEncoded = $signingKey->encode();
$verificationKeyEncoded = $verificationKey->encode();

// 解码密钥
$signingKeyDecoded = AsymmetricSecretKey::fromEncodedString($signingKeyEncoded);
$verificationKeyDecoded = AsymmetricPublicKey::fromEncodedString($verificationKeyEncoded);

PEM格式支持

// 导出为PEM格式
$signingKeyPem = $signingKey->encodePem();
$verificationKeyPem = $verificationKey->encodePem();

// 从PEM导入
$signingKeyFromPem = AsymmetricSecretKey::importPem($signingKeyPem);
$verificationKeyFromPem = AsymmetricPublicKey::importPem($verificationKeyPem);

创建PASETO令牌

简单示例（本地令牌）

use ParagonIE\Paseto\Builder;
use ParagonIE\Paseto\Protocol\Version4;
use ParagonIE\Paseto\Purpose;

$token = (new Builder())
    ->setKey($sharedKey)
    ->setVersion(new Version4)
    ->setPurpose(Purpose::local())
    ->setIssuedAt()
    ->setExpiration((new DateTime())->add(new DateInterval('P01D')))
    ->setClaims([
        'user_id' => 12345,
        'role' => 'admin'
    ]);
    
echo $token; // 输出令牌字符串

令牌解析与验证

use ParagonIE\Paseto\Parser;
use ParagonIE\Paseto\ProtocolCollection;
use ParagonIE\Paseto\Rules\{ValidAt, IssuedBy};

$parser = new Parser()
    ->setKey($sharedKey)
    ->setAllowedVersions(ProtocolCollection::v4())
    ->setPurpose(Purpose::local())
    ->addRule(new ValidAt)
    ->addRule(new IssuedBy('your-issuer-name'));

try {
    $parsedToken = $parser->parse($tokenString);
    // 令牌验证通过
} catch (PasetoException $ex) {
    // 处理无效令牌
}

高级功能：密钥环（Key Rings）

密钥环用于管理多组密钥，特别适合以下场景：

• 与多个第三方身份提供者集成
• 实现密钥轮换策略

接收密钥环（验证用）

use ParagonIE\Paseto\ReceivingKeyRing;

$keyring = new ReceivingKeyRing
    ->setVersion(new Version4)
    ->setPurpose(Purpose::public())
    ->addKey('provider1-key', $verificationKey1)
    ->addKey('provider2-key', $verificationKey2);

发送密钥环（签名用）

use ParagonIE\Paseto\SendingKeyRing;

$keyring = new SendingKeyRing
    ->setVersion(new Version4)
    ->setPurpose(Purpose::local())
    ->addKey('current-key', $sharedKey1)
    ->addKey('previous-key', $sharedKey2);

在构建器和解析器中使用密钥环

// 使用发送密钥环创建令牌
$builder->setKey($sendingKeyRing);
$token = $builder->toString();

// 使用接收密钥环验证令牌
$parser->setKey($receivingKeyRing);
$validToken = $parser->parse($token);

最佳实践

1. 密钥管理：妥善保管签名密钥，定期轮换密钥
2. 令牌有效期：始终设置合理的过期时间
3. 版本控制：明确指定允许的协议版本
4. 验证规则：添加必要的验证规则（如签发者、有效期等）
5. 错误处理：妥善处理解析异常，避免信息泄露

paragonie/paseto通过严格的类型检查和清晰的API设计，帮助开发者避免常见的安全错误，是构建现代安全应用的理想选择。

paseto Platform-Agnostic Security Tokens 项目地址: https://gitcode.com/gh_mirrors/pa/paseto