yoozzeek/actix-csrf-middleware

# actix-csrf-middleware [](https://crates.io/crates/actix-csrf-middleware) [](https://docs.rs/actix-csrf-middleware) [](https://github.com/yoozzeek/actix-csrf-middleware/actions/workflows/ci.yml) [](./LICENSE) 用于 [Actix Web](https://github.com/actix/actix-web) 应用的 CSRF 保护中间件。开箱即支持双重提交 cookie 和同步 token 模式（配合 actix-session）。灵活、易于配置，并包含 针对常见攻击和边缘情况的测试覆盖。 ## ⚠️ 安全警告 此 crate 未经审计，可能包含 bug 和安全漏洞。 使用风险自负！ ## 概述 - 将 CSRF token 存储为： - 无状态的双重提交 cookie - 通过 `actix-session` 存储在持久化存储中的同步 token - 基于以下指南实现 [OWASP CSRF Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html) - CSRF token 是一个 256 位的密码学安全随机值 - 对于双重提交 cookie 模式，使用 HMAC-SHA256 将会话/预会话 ID 与 CSRF token 进行哈希处理 - 以恒定时间比较 token 以防止时序攻击 - 使用已签名的、无状态的预会话保护未授权路由（cookie 始终为 HttpOnly=true, Secure=true, SameSite=Strict） - 自动提取并验证来自以下位置的 token： - `application/json` - `application/x-www-form-urlencoded` - 可配置的 cookie、header 和表单字段名称 - 优雅的、类型化的错误处理：每个拒绝都是一个 `CsrfError`，默认渲染为 `{"error":""}`（JSON，正确的状态码），并带有稳定的机器可读代码。类型化的值存储在 response extensions 中，因此 actix 的 `ErrorHandlers` 可以恢复它并以你自己的格式重新渲染（HTML、JSON、 problem+json）。内部故障在服务器端记录，绝不会向客户端泄露细节。 - 可选的对修改性请求的 Origin/Referer 强制校验（可配置） - 在 handler 级别手动提取和验证 CSRF token 的辅助工具，可用于处理 `multipart/form-data` 请求，而无需在中间件中进行昂贵的 body 读取 - 默认对所有修改性（`POST`,`PUT`,`PATCH`,`DELETE`）http 请求启用；支持通过 `skip_for` 按路径排除 CSRF。 ## 快速开始 依赖项： ``` [dependencies] actix-web = "4" actix-csrf-middleware = "0.6" ``` 代码： ``` use actix_csrf_middleware::{CsrfMiddleware, CsrfMiddlewareConfig, CsrfToken}; use actix_web::{web, App, HttpResponse, HttpServer, Responder}; async fn form(csrf: CsrfToken) -> impl Responder { HttpResponse::Ok().body(format!("csrf token: {}", csrf.0)) } async fn submit() -> impl Responder { // Runs only after the CSRF token is verified. HttpResponse::Ok().body("accepted") } #[actix_web::main] // or #[tokio::main] async fn main() -> std::io::Result<()> { // >= 32 bytes; load from your config in production. let secret = b"replace-me-with-a-32+byte-application-secret"; HttpServer::new(move || { // Constant secret, so tokens validate across workers. let config = CsrfMiddlewareConfig::double_submit_cookie(secret); App::new() .wrap(CsrfMiddleware::new(config)) .route("/", web::get().to(form)) .route("/submit", web::post().to(submit)) }) .bind(("127.0.0.1", 8080))? .run() .await } ``` ## 示例 examples 目录中提供了最小化的可运行示例： - [双重提交 Cookie](examples/double-submit-cookie) - [同步 Token（需要 `actix-session`）](examples/synchronizer-token) - [登录/登出轮转（双重提交 Cookie + RequestExt rotate）](examples/login-logout-rotation) ## 许可证 该项目基于 MIT 许可证授权。详情请参阅 [LICENSE](./LICENSE)。