nosurf

Documentation

Overview

Package nosurf implements an HTTP handler that mitigates Cross-Site request Forgery Attacks.

Index

• Constants
• Variables
• func Default(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 Configurable(handler http.Handler) *CSRFHandler
  • 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) IsExempt(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) SetFailureHandler(handler http.Handler)

Constants

const (
	// CookieName the name of CSRF cookie
	CookieName = "csrf_token"
	// FormFieldName the name of the form field
	FormFieldName = "csrf_token"
	// HeaderName the name of CSRF header
	HeaderName = "X-CSRF-Token"
	// FailureCode the HTTP status code for the default failure handler
	FailureCode = 400
	// MaxAge 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 Default

func Default(handler http.Handler) http.Handler

Default is the same as Configurable(), but has an interface return type.

func Reason

func Reason(req *http.Request) error

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

func Token(req *http.Request) string

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

func VerifyToken(realToken, sentToken string) bool

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 Configurable

func Configurable(handler http.Handler) *CSRFHandler

Configurable Constructs a new CSRFHandler that calls the specified handler if the CSRF check succeeds.

func (*CSRFHandler) ExemptFunc

func (h *CSRFHandler) ExemptFunc(fn func(r *http.Request) bool)

func (*CSRFHandler) ExemptGlob

func (h *CSRFHandler) ExemptGlob(pattern string)

func (*CSRFHandler) ExemptGlobs

func (h *CSRFHandler) ExemptGlobs(patterns ...string)

ExemptGlobs variadic argument version of ExemptGlob()

func (*CSRFHandler) ExemptPath

func (h *CSRFHandler) ExemptPath(path string)

ExemptPath exempts an exact path from CSRF checks with this (and other Exempt* methods)

func (*CSRFHandler) ExemptPaths

func (h *CSRFHandler) ExemptPaths(paths ...string)

ExemptPaths variadic argument version of ExemptPath()

func (*CSRFHandler) ExemptRegexp

func (h *CSRFHandler) ExemptRegexp(re interface{})

ExemptRegexp accepts a regular expression string or a compiled *regexp.Regexp and exempts URLs that match it from CSRF checks.

func (*CSRFHandler) ExemptRegexps

func (h *CSRFHandler) ExemptRegexps(res ...interface{})

ExemptRegexps variadic argument version of ExemptRegexp()

func (*CSRFHandler) IsExempt

func (h *CSRFHandler) IsExempt(r *http.Request) bool

IsExempt 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) RegenerateToken

func (h *CSRFHandler) RegenerateToken(w http.ResponseWriter, r *http.Request) string

RegenerateToken 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)

SetBaseCookie 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) SetFailureHandler

func (h *CSRFHandler) SetFailureHandler(handler http.Handler)

SetFailureHandler sets the handler to call in case the CSRF check fails. By default, it's defaultFailureHandler.