README

在Lithe中的CSRF（跨站请求伪造）中间件是一种安全层，可保护您的应用程序免受未经授权尝试代表用户执行操作攻击。此类攻击可能发生在认证用户访问恶意网站并尝试向您的应用程序发送请求时。

安装

要在您的Lithe应用程序中安装CSRF中间件，请使用Composer。在您的终端中运行以下命令

composer require lithemod/csrf

使用CSRF中间件

应将CSRF中间件配置在您的Lithe应用程序中，以保护更改应用程序状态的路由（例如POST、PUT、DELETE）。要配置它，请使用Lithe应用程序实例上的use()方法将其添加到应用程序中，并提供一个配置数组

use Lithe\Middleware\Security\csrf;

$app->use(csrf([ 
    'expire' => 600, // Token expiration time in seconds
]));

中间件配置

以下是对CSRF中间件可用的配置

name (字符串)：CSRF令牌的名称。默认为_token。您可以根据需要更改它，例如，如果您正在使用期望不同令牌名称的前端框架。
expire (整数)：令牌的过期时间（秒）。默认为600秒（10分钟）。此值应在安全性和可用性之间取得平衡；非常低的值可能会让用户感到沮丧。
checkBody (布尔值)：指示是否应在请求体中验证令牌。默认为false。如果启用，这将确保即使在PUT或DELETE等方法中也会验证令牌。
bodyMethods (数组)：如果启用checkBody配置，则应用令牌验证的HTTP方法。默认为['POST']。这对于使用其他HTTP方法修改数据的端点非常有用。
regenerate (布尔值)：指示是否应在每次请求中重新生成令牌。默认为false。启用此功能可以增强安全性，但在某些情况下可能会影响用户体验。

在路由中的示例配置

$app->use(csrf([ 
    'name' => '_csrf_token', 
    'expire' => 900, // 15 minutes 
    'checkBody' => true, 
    'bodyMethods' => ['POST', 'PUT', 'DELETE'], 
    'regenerate' => true,
]));

生成和检索CSRF令牌

CSRF中间件为每个会话生成一个唯一的令牌。您可以使用以下方法在路由内生成和检索令牌

$app->get('/generate-token', function ($req, $res) {
    $token = $req->csrf->generateToken();
    return $res->json(['token' => $token]);
});

$app->get('/get-token', function ($req, $res) {
    $token = $req->csrf->getToken();
    return $res->json(['token' => $token]);
});

generateToken方法有一个可选参数，当设置为true时，将强制生成新令牌。

在表单中包含CSRF令牌

要将在HTML表单中包含CSRF令牌，请使用getTokenField()方法生成带有令牌的隐藏字段

$app->get('/form', function ($req, $res) {
    $tokenField = $req->csrf->getTokenField();
    return $res->send("
        <form method='POST' action='/submit'>
            $tokenField
            <input type='text' name='data' required>
            <button type='submit'>Submit</button>
        </form>
    ");
});

验证CSRF令牌

当启用checkBody选项时，中间件会自动验证POST请求和其他指定在bodyMethods中的方法中的令牌。如果令牌无效或缺失，将抛出HTTP 419异常。如果禁用checkBody，您可以使用以下方法验证令牌的有效性

$app->post('/submit', function ($req, $res) {
    $token = $req->input('_csrf_token'); // Change to the token name if necessary
    if ($req->csrf->verifyToken($token)) {
        // Process the request
        return $res->json(['message' => 'Data submitted successfully!']);
    } else {
        // Handle the invalid token
        return $res->status(419)->json(['error' => 'Invalid CSRF token!']);
    }
});

令牌操作函数

以下是一些有用的CSRF令牌操作函数

invalidate()：销毁CSRF令牌及其相关会话变量，使其失效。

$app->post('/invalidate-token', function ($req, $res) {
    $req->csrf->invalidate();
    return $res->json(['message' => 'CSRF token invalidated!']);
});

exists()：检查会话中是否存在CSRF令牌。

$app->get('/check-token', function ($req, $res) {
    $exists = $req->csrf->exists();
    return $res->json(['token_exists' => $exists]);
});

安全注意事项

应用程序安全：使用CSRF中间件对于应用程序安全至关重要。始终在所有提交可修改数据的表单和AJAX请求中包含令牌。应妥善处理令牌的缺失或无效性，通常导致重定向或错误消息。
令牌过期：配置令牌过期时间以平衡安全性和可用性。过期令牌应重新生成，如果用户尝试使用无效令牌，则应通知用户。
体验证：启用体验证（checkBody）可以增强安全性，尤其是在使用PUT和DELETE等方法的API中。然而，这可能会增加请求处理的负担，因此请评估您应用程序的需求。
令牌重新生成：在每次请求中启用令牌重新生成可以增加安全性，但如果用户尝试快速提交表单，也可能导致问题。请谨慎使用，并测试以确保良好的用户体验。
错误处理：当CSRF令牌无效或缺失时，应准备处理HTTP 419异常。适当的处理可能包括重定向到错误页面、显示用户友好的消息，甚至记录攻击尝试以供以后分析。
监控和分析：考虑实现日志记录以监控CSRF攻击尝试。这可以帮助识别可疑模式，并进一步增强您应用程序的安全性。

lithemod / csrf

维护者

详情