Documentation ¶
Overview ¶
Package nosurf implements an HTTP handler that mitigates Cross-Site Request Forgery Attacks.
Index ¶
- Constants
- Variables
- func NewPure(handler http.Handler) http.Handler
- func Reason(req *http.Request) error
- func Token(req *http.Request) string
- func VerifyToken(realToken, sentToken string) bool
- type CSRFHandler
- func (h *CSRFHandler) DisableForPath(path string)
- func (h *CSRFHandler) DisableGlob(pattern string)
- func (h *CSRFHandler) DisableGlobs(patterns ...string)
- func (h *CSRFHandler) DisablePath(path string)
- func (h *CSRFHandler) ExemptFunc(fn func(r *http.Request) bool)
- func (h *CSRFHandler) ExemptGlob(pattern string)
- func (h *CSRFHandler) ExemptGlobs(patterns ...string)
- func (h *CSRFHandler) ExemptPath(path string)
- func (h *CSRFHandler) ExemptPaths(paths ...string)
- func (h *CSRFHandler) ExemptRegexp(re interface{})
- func (h *CSRFHandler) ExemptRegexps(res ...interface{})
- func (h *CSRFHandler) IgnoreGlob(pattern string)
- func (h *CSRFHandler) IgnoreGlobs(patterns ...string)
- func (h *CSRFHandler) IgnorePath(path string)
- func (h *CSRFHandler) IsDisabled(r *http.Request) bool
- func (h *CSRFHandler) IsExempt(r *http.Request) bool
- func (h *CSRFHandler) IsIgnored(r *http.Request) bool
- func (h *CSRFHandler) RegenerateToken(w http.ResponseWriter, r *http.Request) string
- func (h *CSRFHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)
- func (h *CSRFHandler) SetBaseCookie(cookie http.Cookie)
- func (h *CSRFHandler) SetBaseCookieFunc(f func(w http.ResponseWriter, r *http.Request) http.Cookie)
- func (h *CSRFHandler) SetFailureHandler(handler http.Handler)
- type Handler
Constants ¶
const ( // the name of CSRF cookie CookieName = "csrf_token" // the name of the form field FormFieldName = "csrf_token" // the name of CSRF header HeaderName = "X-CSRF-Token" // the HTTP status code for the default failure handler FailureCode = 400 // Max-Age in seconds for the default base cookie. 365 days. MaxAge = 365 * 24 * 60 * 60 )
Variables ¶
var ( ErrNoReferer = errors.New("A secure request contained no Referer or its value was malformed") ErrBadReferer = errors.New("A secure request's Referer comes from a different Origin" + " from the request's URL") ErrBadToken = errors.New("The CSRF token in the cookie doesn't match the one" + " received in a form/header.") )
reasons for CSRF check failures
Functions ¶
func Reason ¶
Reason takes an HTTP request and returns the reason of failure of the CSRF check for that request
Note that the same availability restrictions apply for Reason() as for Token().
func Token ¶
Token takes an HTTP request and returns the CSRF token for that request or an empty string if the token does not exist.
Note that the token won't be available after CSRFHandler finishes (that is, in another handler that wraps it, or after the request has been served)
func VerifyToken ¶
VerifyToken verifies the sent token equals the real one and returns a bool value indicating if tokens are equal. Supports masked tokens. realToken comes from Token(r) and sentToken is token sent unusual way.
Types ¶
type CSRFHandler ¶
type CSRFHandler struct {
// contains filtered or unexported fields
}
func New ¶
func New(handler http.Handler) *CSRFHandler
Constructs a new CSRFHandler that calls the specified handler if the CSRF check succeeds.
func (*CSRFHandler) DisableForPath ¶ added in v1.2.1
func (h *CSRFHandler) DisableForPath(path string)
func (*CSRFHandler) DisableGlob ¶ added in v1.2.6
func (h *CSRFHandler) DisableGlob(pattern string)
func (*CSRFHandler) DisableGlobs ¶ added in v1.2.6
func (h *CSRFHandler) DisableGlobs(patterns ...string)
func (*CSRFHandler) DisablePath ¶ added in v1.2.6
func (h *CSRFHandler) DisablePath(path string)
Disables the CSRF middleware for an exact path With this you should take note that Go's paths include a leading slash.
func (*CSRFHandler) ExemptFunc ¶
func (h *CSRFHandler) ExemptFunc(fn func(r *http.Request) bool)
func (*CSRFHandler) ExemptGlob ¶
func (h *CSRFHandler) ExemptGlob(pattern string)
Exempts URLs that match the specified glob pattern (as used by filepath.Match()) from CSRF checks
Note that ExemptGlob() is unable to detect syntax errors, because it doesn't have a path to check it against and filepath.Match() doesn't report an error if the path is empty. If we find a way to check the syntax, ExemptGlob MIGHT PANIC on a syntax error in the future. ALWAYS check your globs for syntax errors.
func (*CSRFHandler) ExemptGlobs ¶
func (h *CSRFHandler) ExemptGlobs(patterns ...string)
A variadic argument version of ExemptGlob()
func (*CSRFHandler) ExemptPath ¶
func (h *CSRFHandler) ExemptPath(path string)
Exempts an exact path from CSRF checks With this (and other Exempt* methods) you should take note that Go's paths include a leading slash.
func (*CSRFHandler) ExemptPaths ¶
func (h *CSRFHandler) ExemptPaths(paths ...string)
A variadic argument version of ExemptPath()
func (*CSRFHandler) ExemptRegexp ¶
func (h *CSRFHandler) ExemptRegexp(re interface{})
Accepts a regular expression string or a compiled *regexp.Regexp and exempts URLs that match it from CSRF checks.
If the given argument is neither of the accepted values, or the given string fails to compile, ExemptRegexp() panics.
func (*CSRFHandler) ExemptRegexps ¶
func (h *CSRFHandler) ExemptRegexps(res ...interface{})
A variadic argument version of ExemptRegexp()
func (*CSRFHandler) IgnoreGlob ¶ added in v1.2.5
func (h *CSRFHandler) IgnoreGlob(pattern string)
func (*CSRFHandler) IgnoreGlobs ¶ added in v1.2.5
func (h *CSRFHandler) IgnoreGlobs(patterns ...string)
func (*CSRFHandler) IgnorePath ¶ added in v1.2.2
func (h *CSRFHandler) IgnorePath(path string)
Ignores the CSRF middleware for an exact path With this you should take note that Go's paths include a leading slash.
func (*CSRFHandler) IsDisabled ¶ added in v1.2.6
func (h *CSRFHandler) IsDisabled(r *http.Request) bool
Checks if the given request disables this middleware
func (*CSRFHandler) IsExempt ¶
func (h *CSRFHandler) IsExempt(r *http.Request) bool
Checks if the given request is exempt from CSRF checks. It checks the ExemptFunc first, then the exact paths, then the globs and finally the regexps.
func (*CSRFHandler) IsIgnored ¶ added in v1.2.2
func (h *CSRFHandler) IsIgnored(r *http.Request) bool
Checks if the given request ignores this middleware
func (*CSRFHandler) RegenerateToken ¶
func (h *CSRFHandler) RegenerateToken(w http.ResponseWriter, r *http.Request) string
Generates a new token, sets it on the given request and returns it
func (*CSRFHandler) ServeHTTP ¶
func (h *CSRFHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)
func (*CSRFHandler) SetBaseCookie ¶
func (h *CSRFHandler) SetBaseCookie(cookie http.Cookie)
Sets the base cookie to use when building a CSRF token cookie This way you can specify the Domain, Path, HttpOnly, Secure, etc.
func (*CSRFHandler) SetBaseCookieFunc ¶ added in v1.2.4
func (h *CSRFHandler) SetBaseCookieFunc(f func(w http.ResponseWriter, r *http.Request) http.Cookie)
Similar to SetBaseCookie but accepts a function which receives the HTTP response and HTTP request for potential contextualization.
func (*CSRFHandler) SetFailureHandler ¶
func (h *CSRFHandler) SetFailureHandler(handler http.Handler)
Sets the handler to call in case the CSRF check fails. By default it's defaultFailureHandler.
type Handler ¶ added in v1.2.6
type Handler interface { http.Handler // RegenerateToken regenerates a CSRF token and sets the cookie. RegenerateToken(w http.ResponseWriter, r *http.Request) string // ExemptPath will not require CSRF validation but will still set the // cookie if it has not yet been set. ExemptPath(string) // IgnorePath will not require CSRF validation and also not set the CSRF // cookie, but it will set the CSRF token (if available) in the request context. IgnorePath(string) // IgnoreGlob behaves similar to IgnorePath but allows defining a glob. IgnoreGlob(string) // IgnoreGlobs behaves similar to IgnorePath but allows defining globs. IgnoreGlobs(...string) // DisablePath will not require CSRF validation and also not set the CSRF // cookie, and it will also not set the CSRF token in the request context. DisablePath(string) // DisableGlob behaves similar to DisablePath but allows defining a glob. DisableGlob(string) // DisableGlobs behaves similar to DisablePath but allows defining globs. DisableGlobs(...string) }