编辑“︁Gin跨站请求伪造保护（CSRF Protection）”︁（章节）

= Gin跨站请求伪造保护（CSRF Protection） =

'''跨站请求伪造'''（Cross-Site Request Forgery，CSRF）是一种常见的网络安全攻击方式，攻击者利用用户已登录的身份，在用户不知情的情况下执行非预期的操作。Gin框架提供了内置的中间件来帮助开发者防范此类攻击。本章将详细介绍CSRF的原理、Gin中的实现方式以及实际应用案例。

== 什么是CSRF攻击？ ==
CSRF攻击利用了Web应用程序对用户浏览器的信任机制。攻击者诱导用户访问恶意网站或点击恶意链接，从而以用户的身份向目标网站发送请求。由于浏览器会自动携带用户的认证信息（如Cookie），目标网站会误认为这是用户的合法请求。

例如：
* 用户登录了银行网站，会话未过期。
* 用户访问了攻击者的网站，该网站包含一个自动提交的表单，向银行网站发起转账请求。
* 银行网站接收到请求后，由于用户已认证，请求被执行。

== Gin中的CSRF保护机制 ==
Gin通过<code>csrf</code>中间件实现防护，该中间件会：
1. 生成并验证CSRF令牌（Token）。
2. 要求所有非幂等请求（如POST、PUT、DELETE）必须携带有效的CSRF令牌。
3. 通过Cookie和表单/Header双重验证确保请求来源可信。

=== 基本配置 ===
以下是一个启用CSRF保护的Gin示例：

<syntaxhighlight lang="go">
package main

import (
    "github.com/gin-gonic/gin"
    "github.com/gin-contrib/csrf"
    "github.com/gin-gonic/gin/render"
)

func main() {
    r := gin.Default()

    // 配置CSRF中间件
    r.Use(csrf.Middleware(csrf.Options{
        Secret: "your-secret-key", // 必须的密钥，用于签名令牌
        ErrorFunc: func(c *gin.Context) {
            c.String(400, "CSRF token mismatch")
            c.Abort()
        },
    }))

    r.GET("/protected", func(c *gin.Context) {
        // 获取当前CSRF令牌（用于前端表单）
        token := csrf.GetToken(c)
        c.HTML(200, "form.html", gin.H{
            "csrfToken": token,
        })
    })

    r.POST("/submit", func(c *gin.Context) {
        c.String(200, "Request processed successfully")
    })

    r.Run(":8080")
}
</syntaxhighlight>

=== 前端集成 ===
在HTML表单中必须嵌入CSRF令牌：

<syntaxhighlight lang="html">
<form action="/submit" method="POST">
    <input type="hidden" name="_csrf" value="{{ .csrfToken }}">
    <input type="text" name="amount">
    <button type="submit">Submit</button>
</form>
</syntaxhighlight>

或通过Header传递（适用于AJAX请求）：
<syntaxhighlight lang="javascript">
fetch('/submit', {
    method: 'POST',
    headers: {
        'X-CSRF-Token': 'YOUR_CSRF_TOKEN_HERE'
    },
    body: JSON.stringify({ amount: 100 })
});
</syntaxhighlight>

== 工作原理 ==
Gin的CSRF保护流程如下：
<mermaid>
sequenceDiagram
    participant Client
    participant Server
    Client->>Server: GET /protected
    Server->>Client: 返回HTML + CSRF令牌（Cookie和表单）
    Client->>Server: POST /submit (携带Cookie和表单令牌)
    Server->>Server: 验证Cookie令牌与表单令牌是否匹配
    alt 验证成功
        Server->>Client: 200 OK
    else 验证失败
        Server->>Client: 400 Bad Request
    end
</mermaid>

=== 数学原理 ===
令牌生成使用HMAC算法：
<math>
\text{Token} = \text{HMAC-SHA256}(\text{Secret}, \text{SessionID} \parallel \text{Timestamp})
</math>

== 实际案例 ==
=== 案例1：用户资料修改 ===
攻击者可能伪造以下请求：
<syntaxhighlight lang="html">
<!-- 恶意网站代码 -->
<form action="https://example.com/profile/update" method="POST">
    <input type="hidden" name="email" value="attacker@example.com">
</form>
<script>document.forms[0].submit();</script>
</syntaxhighlight>

启用CSRF保护后，由于缺少有效令牌，请求将被拒绝。

=== 案例2：AJAX请求防护 ===
即使使用AJAX，也需要添加CSRF令牌头：
<syntaxhighlight lang="javascript">
// 从Cookie读取令牌
function getCookie(name) {
    let value = `; ${document.cookie}`;
    let parts = value.split(`; ${name}=`);
    if (parts.length === 2) return parts.pop().split(';').shift();
}

fetch('/api/transfer', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'X-CSRF-Token': getCookie('_csrf')
    },
    body: JSON.stringify({ to: 'account123', amount: 1000 })
});
</syntaxhighlight>

== 高级配置 ==
=== 自定义选项 ===
<code>csrf.Options</code>支持以下配置：
* <code>Secret</code>：签名密钥（必需）
* <code>FieldName</code>：表单字段名（默认<code>_csrf</code>）
* <code>CookieName</code>：Cookie名称（默认<code>_csrf</code>）
* <code>CookieDomain</code>：Cookie作用域
* <code>Secure</code>：仅HTTPS传输（生产环境应为true）

示例：
<syntaxhighlight lang="go">
r.Use(csrf.Middleware(csrf.Options{
    Secret: "32-byte-long-secret-key-here",
    CookieName: "custom_csrf_cookie",
    Secure: true,
    ErrorFunc: func(c *gin.Context) {
        c.JSON(403, gin.H{"error": "CSRF validation failed"})
    },
}))
</syntaxhighlight>

== 常见问题 ==
'''Q：为什么GET请求不需要CSRF保护？'''
A：根据HTTP规范，GET请求只应用于数据获取而非状态修改。但仍建议对敏感操作使用POST/PUT/DELETE。

'''Q：如何测试CSRF防护？'''
A：使用工具如curl模拟恶意请求：
<syntaxhighlight lang="bash">
# 缺少令牌的请求应失败
curl -X POST http://localhost:8080/submit
</syntaxhighlight>

== 最佳实践 ==
1. 对所有状态修改操作启用CSRF保护
2. 生产环境使用HTTPS并设置<code>Secure: true</code>
3. 定期轮换CSRF密钥
4. 避免在URL中传递敏感令牌（可能被日志记录）

通过本章学习，您应该已经掌握Gin框架中CSRF防护的实现方法和实际应用场景。

[[Category:后端框架]]
[[Category:Gin]]
[[Category:Gin身份验证与授权]]