README
¶
filippo.io/csrf
This package provides protection against Cross-Site Request Forgery (CSRF) attacks using modern browser Fetch metadata headers.
It requires no tokens or cookies, and works with all browsers since 2020.
package main
import (
"net/http"
"filippo.io/csrf"
)
func main() {
mux := http.NewServeMux()
mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
fmt.Fprintf(w, "Hello, world!")
})
protection := csrf.New()
handler := protection.Handler(mux)
http.ListenAndServe(":8080", handler)
}
For full API documentation, including bypass mechanisms, see pkg.go.dev.
For more information on this approach, see the standard library proposal.
github.com/gorilla/csrf compatibility
The filippo.io/csrf/gorilla package provides a drop-in replacement for the
github.com/gorilla/csrf package. It implements the same API, but uses the
modern Fetch metadata headers instead of tokens and cookies.
Read the full package documentation for full migration details.
import (
+ csrf "filippo.io/csrf/gorilla"
- "github.com/gorilla/csrf"
)
Documentation
¶
Overview ¶
Package csrf implements protections against Cross-Site Request Forgery (CSRF) equivalent to those provided by http.CrossOriginProtection, introduced in Go 1.25.
The gorilla subpackage implements a drop-in replacement for the github.com/gorilla/csrf package.
Index ¶
- func UnsafeBypassRequest(r *http.Request) *http.Request
- type Protection
- func (c *Protection) AddTrustedOrigin(origin string) error
- func (c *Protection) AddUnsafeBypassPattern(pattern string)
- func (c *Protection) Check(req *http.Request) error
- func (c *Protection) Handler(h http.Handler) http.Handler
- func (c *Protection) HandlerWithFailHandler(h http.Handler, fail http.Handler) http.Handler
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Protection ¶
type Protection struct {
// contains filtered or unexported fields
}
Protection implements protections against Cross-Site Request Forgery (CSRF) by rejecting non-safe cross-origin browser requests.
Cross-origin requests are currently detected with the Sec-Fetch-Site header, available in all browsers since 2023, or by comparing the hostname of the Origin header with the Host header.
The GET, HEAD, and OPTIONS methods are safe methods and are always allowed. It's important that applications do not perform any state changing actions due to requests with safe methods.
Requests without Sec-Fetch-Site or Origin headers are currently assumed to be either same-origin or non-browser requests, and are allowed.
The zero value of Protection is valid and has no trusted origins or bypass patterns.
func (*Protection) AddTrustedOrigin ¶
func (c *Protection) AddTrustedOrigin(origin string) error
AddTrustedOrigin allows all requests with an Origin header which exactly matches the given value.
Origin header values are of the form "scheme://host[:port]".
AddTrustedOrigin can be called concurrently with other methods or request handling, and applies to future requests.
func (*Protection) AddUnsafeBypassPattern ¶
func (c *Protection) AddUnsafeBypassPattern(pattern string)
AddUnsafeBypassPattern permits all requests that match the given pattern. The pattern syntax and precedence rules are the same as [ServeMux].
AddUnsafeBypassPattern can be called concurrently with other methods or request handling, and applies to future requests.
func (*Protection) Check ¶
func (c *Protection) Check(req *http.Request) error
Check applies cross-origin checks to a request. It returns an error if the request should be rejected.
func (*Protection) Handler ¶
func (c *Protection) Handler(h http.Handler) http.Handler
Handler returns a handler that applies cross-origin checks before invoking the handler h.
If a request fails cross-origin checks, the request is rejected with a 403 Forbidden status.
func (*Protection) HandlerWithFailHandler ¶
HandlerWithFailHandler returns a handler that applies cross-origin checks before invoking the handler h.
If a request fails cross-origin checks, the request is handled with the given failure handler.
Source Files
Directories