csrf

Documentation

Index

• Constants
• Variables
• func FromCookie(param string) func(c fiber.Ctx) (string, error)
• func FromForm(param string) func(c fiber.Ctx) (string, error)
• func FromHeader(param string) func(c fiber.Ctx) (string, error)
• func FromParam(param string) func(c fiber.Ctx) (string, error)
• func FromQuery(param string) func(c fiber.Ctx) (string, error)
• func New(config ...Config) fiber.Handler
• func TokenFromContext(c fiber.Ctx) string
• type Config
• type Handler
  • func HandlerFromContext(c fiber.Ctx) *Handler
  • func (handler *Handler) DeleteToken(c fiber.Ctx) error
• type Token

Constants

const HeaderName = "X-Csrf-Token"

Variables

var (
	ErrTokenNotFound   = errors.New("csrf token not found")
	ErrTokenInvalid    = errors.New("csrf token invalid")
	ErrRefererNotFound = errors.New("referer not supplied")
	ErrRefererInvalid  = errors.New("referer invalid")
	ErrRefererNoMatch  = errors.New("referer does not match host and is not a trusted origin")
	ErrOriginInvalid   = errors.New("origin invalid")
	ErrOriginNoMatch   = errors.New("origin does not match host and is not a trusted origin")
)

var (
	ErrMissingHeader = errors.New("missing csrf token in header")
	ErrMissingQuery  = errors.New("missing csrf token in query")
	ErrMissingParam  = errors.New("missing csrf token in param")
	ErrMissingForm   = errors.New("missing csrf token in form")
	ErrMissingCookie = errors.New("missing csrf token in cookie")
)

var ConfigDefault = Config{
	KeyLookup:      "header:" + HeaderName,
	CookieName:     "csrf_",
	CookieSameSite: "Lax",
	Expiration:     1 * time.Hour,
	KeyGenerator:   utils.UUIDv4,
	ErrorHandler:   defaultErrorHandler,
	Extractor:      FromHeader(HeaderName),
	SessionKey:     "csrfToken",
}

ConfigDefault is the default config

Functions

func FromCookie

func FromCookie(param string) func(c fiber.Ctx) (string, error)

FromCookie returns a function that extracts token from the cookie header.

func FromForm

func FromForm(param string) func(c fiber.Ctx) (string, error)

FromForm returns a function that extracts a token from a multipart-form.

func FromHeader

func FromHeader(param string) func(c fiber.Ctx) (string, error)

FromHeader returns a function that extracts token from the request header.

func FromParam

func FromParam(param string) func(c fiber.Ctx) (string, error)

FromParam returns a function that extracts token from the url param string.

func FromQuery

func FromQuery(param string) func(c fiber.Ctx) (string, error)

FromQuery returns a function that extracts token from the query string.

func New

func New(config ...Config) fiber.Handler

New creates a new middleware handler

func TokenFromContext

func TokenFromContext(c fiber.Ctx) string

TokenFromContext returns the token found in the context returns an empty string if the token does not exist

Types

type Config

type Config struct {
	// Next defines a function to skip this middleware when returned true.
	//
	// Optional. Default: nil
	Next func(c fiber.Ctx) bool

	// KeyLookup is a string in the form of "<source>:<key>" that is used
	// to create an Extractor that extracts the token from the request.
	// Possible values:
	// - "header:<name>"
	// - "query:<name>"
	// - "param:<name>"
	// - "form:<name>"
	// - "cookie:<name>"
	//
	// Ignored if an Extractor is explicitly set.
	//
	// Optional. Default: "header:X-Csrf-Token"
	KeyLookup string

	// Name of the session cookie. This cookie will store session key.
	// Optional. Default value "csrf_".
	// Overridden if KeyLookup == "cookie:<name>"
	CookieName string

	// Domain of the CSRF cookie.
	// Optional. Default value "".
	CookieDomain string

	// Path of the CSRF cookie.
	// Optional. Default value "".
	CookiePath string

	// Indicates if CSRF cookie is secure.
	// Optional. Default value false.
	CookieSecure bool

	// Indicates if CSRF cookie is HTTP only.
	// Optional. Default value false.
	CookieHTTPOnly bool

	// Value of SameSite cookie.
	// Optional. Default value "Lax".
	CookieSameSite string

	// Decides whether cookie should last for only the browser sesison.
	// Ignores Expiration if set to true
	CookieSessionOnly bool

	// Expiration is the duration before csrf token will expire
	//
	// Optional. Default: 1 * time.Hour
	Expiration time.Duration

	// SingleUseToken indicates if the CSRF token be destroyed
	// and a new one generated on each use.
	//
	// Optional. Default: false
	SingleUseToken bool

	// Store is used to store the state of the middleware
	//
	// Optional. Default: memory.New()
	// Ignored if Session is set.
	Storage fiber.Storage

	// Session is used to store the state of the middleware
	//
	// Optional. Default: nil
	// If set, the middleware will use the session store instead of the storage
	Session *session.Store

	// SessionKey is the key used to store the token in the session
	//
	// Default: "csrfToken"
	SessionKey string

	// TrustedOrigins is a list of trusted origins for unsafe requests.
	// For requests that use the Origin header, the origin must match the
	// Host header or one of the TrustedOrigins.
	// For secure requests, that do not include the Origin header, the Referer
	// header must match the Host header or one of the TrustedOrigins.
	//
	// This supports matching subdomains at any level. This means you can use a value like
	// `"https://*.example.com"` to allow any subdomain of `example.com` to submit requests,
	// including multiple subdomain levels such as `"https://sub.sub.example.com"`.
	//
	// Optional. Default: []
	TrustedOrigins []string

	// KeyGenerator creates a new CSRF token
	//
	// Optional. Default: utils.UUID
	KeyGenerator func() string

	// ErrorHandler is executed when an error is returned from fiber.Handler.
	//
	// Optional. Default: DefaultErrorHandler
	ErrorHandler fiber.ErrorHandler

	// Extractor returns the csrf token
	//
	// If set this will be used in place of an Extractor based on KeyLookup.
	//
	// Optional. Default will create an Extractor based on KeyLookup.
	Extractor func(c fiber.Ctx) (string, error)
}

Config defines the config for middleware.

type Handler

type Handler struct {
	// contains filtered or unexported fields
}

Handler for CSRF middleware

func HandlerFromContext

func HandlerFromContext(c fiber.Ctx) *Handler

HandlerFromContext returns the Handler found in the context returns nil if the handler does not exist

func (*Handler) DeleteToken

func (handler *Handler) DeleteToken(c fiber.Ctx) error

DeleteToken removes the token found in the context from the storage and expires the CSRF cookie

type Token

type Token struct {
	Key        string    `json:"key"`
	Raw        []byte    `json:"raw"`
	Expiration time.Time `json:"expiration"`
}