秋来冬风的博客

Go1.25's New CSRF (Cross Site Request Forgery) Defense API | Build a More Secure Internet

目录

Software translation

Background

Go1.25 has been released in mid August 2025.

In this update, an API for defending against CSRF (Cross Site Request Forgery) has been added to the net/http package of the standard library. This API is maintained by Filippo Valsorda, the Go language password package maintainer（ https://filippo.io ）Proposed and added to the standard library, he is a cryptographer.

CSRF Implementation Principle

The principle of CSRF is that when a browser sends a request to a website, it will automatically send the cookies saved by that website at the same time.

This means that there is a situation where a user clicks on a malicious link and automatically sends a request to a special website (such as the user’s online banking), because at the same time, the cookie saved by this website is automatically sent. The server sees the user’s cookie and believes it is the user’s own request, resulting in some malicious behavior such as transferring money from the user’s bank card being executed.

Add cause

Filippo Valsorda Two widely used Go libraries for defending against CSRF attacks seem to be in a state of lack of maintenance (such as reporting security issues for weeks without response).

Some vulnerabilities in these libraries have been consistently present since their initial release in 2015, and there are also requirements for developers to manage a key to use signature token cookies. This issue has been discussed with other experts, and the conclusion is that the signature and key are invalid.

New API

API Signature

type CrossOriginProtection struct {}

func NewCrossOriginProtection() *CrossOriginProtection 

func (c *CrossOriginProtection) AddTrustedOrigin(origin string) error 

func (c *CrossOriginProtection) AddInsecureBypassPattern(pattern string) 

func (c *CrossOriginProtection) Check(req *http.Request) error 

func (c *CrossOriginProtection) Handler(h http.Handler) http.Handler

func (c *CrossOriginProtection) SetDenyHandler(h http.Handler)

The API documentation is available https://pkg.go.dev/net/http#CrossOriginProtection

Principles of API Implementation

In the past, some measures to defend against CSRF (CSRF tokens, SameSite cookies, Origin headers, etc.) either required developers to make extra efforts (such as modifying HTML forms) or had various other issues.

The new API added by Go1.25 defends against CSRF through the following methods:

  1. If the request method is a secure method (GET, HEAD, OPTIONS), pass it directly;
  2. Otherwise, check Sec-Fetch-Site:
    • Pass for “same origin” and “none” → pass;
    • Check if bypass is allowed for other non null values. If yes, pass; otherwise, intercept;
  3. If Sec-Fetch-Site is empty, check Origin:
    • Origin is empty → passed;
    • Origin’s Host is consistent with the requested Host → Passed;
  4. Otherwise, check if bypassing is allowed. If yes, pass, otherwise intercept.

The key point is these key value pairs in the HTTP header:

  • Sec-Fetch-Site (available in all major browsers since 2023)
  • Origin (defined in RFC 6454, automatically sent by the browser upon cross source requests)
  • Host (required by section 5.4 of RFC 7230 (HTTP/1.1) standard)

CSRF needs to be performed in the user’s browser, so forging these key value pairs would violate the implementation principles of the attack. For example, if Sec-Fetch-Site is genuine, it will not pass the inspection, and if it is forged, there will be no user cookies automatically sent by the browser**

The same applies to other key value pairs.

The Troubles of Past Defense Methods

CSRF tokens require modifying HTML forms and additional database storage for the tokens.

SameSite cookies cannot defend against attacks between different subdomains within the same site.

The Origin Header has similar issues to the above and is not sent in certain types of requests.

Advantages of the New API

  • No need to modify HTML forms or other elements, requiring no extra effort
  • Can defend against attacks between different subdomains within the same site
  • Defense can be enabled with just one line of code (http.NewCrossOriginProtection().Handler(mux))

Points to Note

Maintain Semantics of Safe Methods

For HTTP safe methods like GET, maintain their semantics and do not use these methods for sensitive operations.

The new API only defends against CSRF attacks caused by browsers automatically sending cookies. It is ineffective if the user’s cookies have already been stolen.

In practice, set the HttpOnly and Secure flags for cookies to prevent cookie theft.

Scenarios with High Security Requirements

For scenarios with high security requirements such as finance and e-commerce, CSRF tokens can be used. This prevents outdated browsers—due to missing the required key-value pairs for HTTP Headers—from incorrectly passing verification when under attack.

Tags: