README

Yii CSRF 保护库

该包提供了用于 CSRF 保护PSR-15 中间件

它支持两种内置算法
- 通过可自定义的令牌生成和存储与同步器 CSRF 令牌同步。默认情况下，它使用随机数据和会话。
- 基于 HMAC 的令牌，具有可自定义的身份生成。默认情况下使用会话。
它具有将掩码应用于 CSRF 令牌字符串的能力，从而使 BREACH 攻击不可能。

要求

PHP 7.4 或更高版本。

安装

可以使用 Composer 安装该包

composer require yiisoft/csrf

一般使用

为了启用 CSRF 保护，您需要将 CsrfMiddleware 添加到您的主中间件堆栈中。在 Yii 中，这是通过配置 config/web/application.php 实现的

return [
    Yiisoft\Yii\Http\Application::class => [
        '__construct()' => [
            'dispatcher' => DynamicReference::to(static function (Injector $injector) {
                return ($injector->make(MiddlewareDispatcher::class))
                    ->withMiddlewares(
                        [
                            ErrorCatcher::class,
                            SessionMiddleware::class,
                            CsrfMiddleware::class, // <-- add this
                            Router::class,
                        ]
                    );
            }),
        ],
    ],
];

默认情况下，CSRF 令牌从 _csrf 请求体参数或 X-CSRF-Token 标头中获取。

您可以使用 CsrfTokenInterface 以字符串形式访问当前有效的令牌

/** @var Yiisoft\Csrf\CsrfTokenInterface $csrfToken */
$csrf = $csrfToken->getValue();

如果令牌未通过验证，将返回响应 422 Unprocessable Entity。您可以通过实现自己的请求处理器来更改此行为

use Psr\Http\Message\ResponseFactoryInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\RequestHandlerInterface;
use Yiisoft\Csrf\CsrfMiddleware;

/**
 * @var Psr\Http\Message\ResponseFactoryInterface $responseFactory
 * @var Yiisoft\Csrf\CsrfTokenInterface $csrfToken
 */
 
$failureHandler = new class ($responseFactory) implements RequestHandlerInterface {
    private ResponseFactoryInterface $responseFactory;
    
    public function __construct(ResponseFactoryInterface $responseFactory)
    {
        $this->responseFactory = $responseFactory;
    }

    public function handle(ServerRequestInterface $request): ResponseInterface
    {
        $response = $this->responseFactory->createResponse(400);
        $response
            ->getBody()
            ->write('Bad request.');
        return $response;
    }
};

$middleware = new CsrfMiddleware($responseFactory, $csrfToken, $failureHandler);

CSRF 令牌

如果与配置插件一起使用 Yii 框架，则该包将自动配置为使用同步器令牌和掩码装饰器。您可以根据需要更改此设置。

同步器 CSRF 令牌

同步器 CSRF 令牌是一种状态化的 CSRF 令牌，是一个唯一的随机字符串。它保存在仅对当前登录用户可用的持久存储中。相同的令牌添加到表单中。当表单提交时，从表单中提交的令牌与存储的令牌进行比较。

SynchronizerCsrfToken 需要实现以下接口

CsrfTokenGeneratorInterface 用于生成新的 CSRF 令牌；
CsrfTokenStorageInterface 用于在请求之间持久化令牌。

包提供了 RandomCsrfTokenGenerator，它生成随机令牌，以及 SessionCsrfTokenStorage，它将令牌在用户会话中持久化。

有关同步器令牌模式的更多信息，请查看 OWASP CSRF 指南。

基于 HMAC 的令牌

基于 HMAC 的令牌是一种无状态的 CSRF 令牌，不需要任何存储。令牌是会话 ID 和时间戳的散列，用于防止重放攻击。令牌添加到表单中。当表单提交时，我们从当前会话 ID 和原始令牌中的时间戳重新生成令牌。如果两个散列匹配，我们将检查时间戳是否小于令牌有效期。

HmacCsrfToken 需要实现 CsrfTokenIdentityGeneratorInterface 以生成身份。该包提供了 SessionCsrfTokenIdentityGenerator，它使用会话 ID，因此使会话成为令牌作用域。

通过 HmacCsrfToken 构造函数设置的参数

$secretKey — 用于生成散列的共享密钥；
$algorithm — 消息认证的哈希算法。建议使用 sha256、sha384 或 sha512；
$lifetime — 令牌有效的秒数。

要了解更多关于基于HMAC的令牌模式，请查阅OWASP CSRF 情报单。

占位符 CSRF 令牌

StubCsrfToken 仅存储并返回一个令牌字符串。它不执行任何额外的验证。在单元测试中模拟 CSRF 令牌行为或提供临时解决方案中的占位符功能时，此实现可能很有用。

掩码 CSRF 令牌

MaskedCsrfToken 是 CsrfTokenInterface 的装饰器，对令牌字符串应用掩码。它使 BREACH 攻击成为不可能，因此可以在 HTML 中安全地使用令牌，稍后作为隐藏表单字段或通过 JavaScript 异步请求传递给下一个请求。

建议始终使用此装饰器。

文档

内部实现

如果您需要帮助或有疑问，Yii 论坛是一个不错的选择。您还可以查看其他 Yii 社区资源。

许可

Yii CSRF 保护库是免费软件。它根据BSD许可证条款发布。有关更多信息，请参阅LICENSE。

由 Yii 软件维护。

yiisoft / csrf

维护者

详细信息