README

关于

提供用于生成和验证针对跨站请求伪造的令牌的类。

注意：不要将此类视为保护您的网站/应用程序的最终方法。如果您想深入了解如何防止CSRF，可以从这里开始。

要求

此包需要

• php 7.0 适用于版本 v1.1.2 及之前版本
• php 7.1 适用于版本 v1.2.0 及之后版本
• php 7.4 适用于版本 v1.4.0 及之后版本
• php 8.1 适用于版本 v2.0.0 及之后版本

安装

使用 composer

composer require linna/csrf-guard

令牌类型

注意：存储数据（关于令牌或令牌本身）的目的是在会话中。

此包提供三种类型的令牌

• 基于加密的 CSRF 令牌
• 基于 HMAC 的 CSRF 令牌
• 同步 CSRF 令牌

基于加密的令牌

基于加密的 CSRF 令牌是使用加密算法生成的令牌，使用只有服务器才知道的秘密密钥加密一些数据。此库的实现使用 libsodium 的 aead 构造 XChaCha20-Poly1305。令牌有过期时间，需要本地存储。

令牌的安全性取决于

• 秘密密钥存储
• XChaCha20-Poly1305 的强度

此令牌在验证或过期之前有效。可以选择令牌的长度。令牌的长度不影响使用的存储。

用于加密的密钥为每个会话生成，每个令牌的nonce。

基于 HMAC 的令牌

基于 HMAC 的 CSRF 令牌是通过将一些数据与应用到 HMAC 函数和一个只有服务器才知道的秘密密钥来计算的令牌。此库的实现使用 php 的 hash_hmac 和 sha3-384 算法。此类型的令牌不需要本地存储，并且有过期时间。

令牌的安全性取决于

• 秘密密钥存储
• sha3-384 的强度

此令牌在过期之前有效，并且可以被验证多次。它还有固定长度，无法更改以获得更短或更长的令牌。

用于验证的密钥完全由库的用户管理。

同步令牌

同步 CSRF 令牌是由随机生成的令牌。此库使用 php 的 random_bytes。令牌有过期时间，需要本地存储。

令牌的安全性取决于

• 令牌的长度

此令牌在验证或过期之前有效。可以选择令牌的长度。令牌的长度会影响使用的存储。

使用方法

注意：在创建提供程序的实例之前，必须启动会话，否则将抛出 SessionNotStartedException，但使用 HmacTokenProvider 时不适用。

入门

如何使用几行代码获取和验证令牌。

生成提供程序

//start the session
\session_start();

//generate token provider
$provider = ProviderSimpleFactory::getProvider();

获取令牌

//previous php code

//get a token from provider
$token = $provider->getToken();

验证它

//previous php code

//true if valid, false otherwise
$isValid = $provider->validate($token);

提供程序配置

ProviderSimpleFactory::getProvider() 静态方法有两个参数

• 提供程序
• 提供程序选项

加密令牌提供程序配置

使用示例

//start the session
\session_start();

//get specific encryption token provider
$provider = ProviderSimpleFactory::getProvider(
    provider: EncryptionTokenProvider::class, // specific token provider
    options: [                                // options
        'expire' => 3600,                     // token expire in 3600 seconds, 1 hour
        'storageSize' => 16,                  // provider can store maximum 1 key and 16 nonces per session,
        'tokenLength' => 16                   // desidered token length in bytes, token will be used as plaintext and not stored
    ]
);

HmacTokenProvider 配置

使用示例

//get specific hmac token provider
$provider = ProviderSimpleFactory::getProvider(
    provider: HmacTokenProvider::class,             // specific token provider
    options: [                                      // options
        'value' => 'value will be hashed in token', // value will be hashed in token
        'key' => 'key_to_authenticate'              // key to authenticate the hash
    ]
);

同步令牌提供程序配置

使用示例

//start the session
\session_start();

//get specific syncronizer token provider
$provider = ProviderSimpleFactory::getProvider(
    provider: SynchronizerTokenProvider::class, // specific token provider
    options: [                                  // options
        'expire' => 3600,                       // token expire in 3600 seconds, 1 hour
        'storageSize' => 16,                    // provider can store maximum 16 token per session,
        'tokenLength' => 32                     // desidered token length in bytes, token will be the double in chars
    ]
);