Documentation
¶
Overview ¶
Package csrf is a drop-in replacement for github.com/gorilla/csrf.
import ( + csrf "filippo.io/csrf/gorilla" - "github.com/gorilla/csrf" )
Instead of tokens and cookies, this package uses Fetch metadata headers provided by modern browsers, like the CSRF protection introduced in the standard library with Go 1.25.
Note that tokens are completely ignored. If github.com/gorilla/csrf was (mis)used for security goals beyond Cross-Site Request Forgery protection, such as for authentication, this might be unexpected. In particular, all non-browser requests (those missing both Sec-Fetch-Site and Origin headers) are allowed, since CSRF is fundamentally a browser issue.
Same-origin vs tokens ¶
github.com/gorilla/csrf v1.7.2 and older allowed any request as long as it had a valid token. v1.7.3 switched to additionally enforcing same-origin requests to fix CVE-2025-24358.
This package exclusively enforces same-origin requests. This means it is stricter than v1.7.2 (and not vulnerable to CVE-2025-24358), but more compatible than v1.7.3.
For example, it works with reverse-proxies, with localhost, and with same-origin HTTP requests without having to use TrustedOrigins or PlaintextHTTPRequest (introduced in v1.7.3, and ignored by this package).
API compatibility ¶
All github.com/gorilla/csrf v1.7.3 exported APIs are also exported by this package, for drop-in compatibility, but many are replaced with stubs.
Token returns a random value which is ignored by this package. TemplateField returns an input HTML tag, which likewise is ignored by this package. Both are provided in case other parts of the application rely on a random value being present.
TrustedOrigins accepts a list of origins, including their schema (e.g. "https://example.com"). For compatibility with github.com/gorilla/csrf, schema-less hosts (e.g. "example.com") are implicitly prefixed with "https://".
Index ¶
- Constants
- Variables
- func FailureReason(r *http.Request) error
- func PlaintextHTTPRequest(r *http.Request) *http.Requestdeprecated
- func Protect(authKey []byte, opts ...Option) func(http.Handler) http.Handler
- func TemplateField(r *http.Request) template.HTMLdeprecated
- func Token(r *http.Request) stringdeprecated
- func UnsafeSkipCheck(r *http.Request) *http.Request
- type Option
- func CookieName(name string) Optiondeprecated
- func Domain(domain string) Optiondeprecated
- func ErrorHandler(h http.Handler) Option
- func FieldName(name string) Optiondeprecated
- func HttpOnly(h bool) Optiondeprecated
- func MaxAge(age int) Optiondeprecated
- func Path(p string) Optiondeprecated
- func RequestHeader(header string) Optiondeprecated
- func SameSite(s SameSiteMode) Optiondeprecated
- func Secure(s bool) Optiondeprecated
- func TrustedOrigins(origins []string) Option
- type SameSiteModedeprecated
Constants ¶
const PlaintextHTTPContextKey contextKey = "plaintext"
PlaintextHTTPContextKey is a stub, exported for drop-in compatibility with the github.com/gorilla/csrf API. It is not used by this package.
Deprecated: all uses of PlaintextHTTPContextKey can be removed. The system in this package does not primarily rely on Origin and Referer headers, so it doesn't need to be informed of what protocol the request came over.
Variables ¶
var ( ErrNoReferer = errors.New("referer not supplied") ErrBadOrigin = errors.New("origin invalid") ErrBadReferer = errors.New("referer invalid") ErrNoToken = errors.New("CSRF token not found in request") ErrBadToken = errors.New("CSRF token invalid") )
These errors are exported for drop-in compatibility with the github.com/gorilla/csrf API. They are not used in this package.
var TemplateTag = "csrfField"
TemplateTag is a stub, exported for drop-in compatibility with the github.com/gorilla/csrf API. It is not used by this package.
Functions ¶
func FailureReason ¶
FailureReason extracts the csrf.Protection.Check return value from the request context.
func PlaintextHTTPRequest
deprecated
PlaintextHTTPRequest is a stub, exported for drop-in compatibility with the github.com/gorilla/csrf API.
It actually applies the PlaintextHTTPContextKey context to the request, in case the application somehow explicitly relies on it, but this package doesn't use it.
Deprecated: all uses of PlaintextHTTPRequest can be removed. The system in this package does not primarily rely on Origin and Referer headers, so it doesn't need to be informed of what protocol the request came over.
func Protect ¶
Protect is an HTTP middleware that provides Cross-Site Request Forgery protection. See csrf.Protection for details.
authKey is ignored and can be nil. Any options except ErrorHandler and TrustedOrigins are also ignored.
func TemplateField
deprecated
TemplateField is a stub, exported for drop-in compatibility with the github.com/gorilla/csrf API. It returns a hidden input field with a random value, in case applications somehow rely on it returning a random, hard to guess value, or in case the server expects a specific field name in the form.
Note that unlike the original github.com/gorilla/csrf package, TemplateField HTML-escapes the field name.
Deprecated: all uses of TemplateField can be removed. The system in this package does not rely on tokens and doesn't require HTML tags.
func Token
deprecated
Token is a stub, exported for drop-in compatibility with the github.com/gorilla/csrf API. It returns a random string, in case applications somehow rely on it returning a random, hard to guess value.
Deprecated: all uses of Token can be removed. The system in this package does not rely on tokens.
Types ¶
type Option ¶
type Option func(*options)
func CookieName
deprecated
func ErrorHandler ¶
ErrorHandler changes the handler that is called when a request is blocked. By default, requests are rejected with a plain HTTP 403 Forbidden response.
func FieldName
deprecated
FieldName is a stub, exported for drop-in compatibility with the github.com/gorilla/csrf API. It still affects TemplateField in case the server expects a specific field name in the form.
Deprecated: all uses of FieldName can be removed. The system in this package does not rely on tokens.
func RequestHeader
deprecated
RequestHeader is a stub, exported for drop-in compatibility with the github.com/gorilla/csrf API.
Deprecated: all uses of RequestHeader can be removed. The system in this package does not rely on tokens. Any request without Sec-Fetch-Site or Origin headers is assumed not to be from a browser, and is allowed.
func SameSite
deprecated
func SameSite(s SameSiteMode) Option
SameSite is a stub, exported for drop-in compatibility with the github.com/gorilla/csrf API.
Deprecated: all uses of SameSite can be removed. The system in this package does not rely on cookies.
func TrustedOrigins ¶
TrustedOrigins configures a set of origins that bypass CSRF checks.
For compatibility with github.com/gorilla/csrf, the origins may omit the schema, in which case it will be assumed to be "https". To allow an HTTP origin, explicitly list it with a schema (e.g. "http://example.com") but note that network attackers may cause requests to be initiated from plain HTTP origins.
type SameSiteMode
deprecated
type SameSiteMode int
SameSiteMode is a stub, exported for drop-in compatibility with the github.com/gorilla/csrf API.
Deprecated: all uses of SameSiteMode can be removed. The system in this package does not rely on cookies.
const ( SameSiteDefaultMode SameSiteMode = iota + 1 SameSiteLaxMode SameSiteStrictMode SameSiteNoneMode )
Source Files