csrf

README

CSRF Middleware

CSRF middleware for Fiber that provides Cross-site request forgery protection by passing a csrf token via cookies. This cookie value will be used to compare against the client csrf token in POST requests. When the csrf token is invalid, this middleware will delete the csrf_ cookie and return the fiber.ErrForbidden error. CSRF Tokens are generated on GET requests. You can retrieve the CSRF token with c.Locals(contextKey), where contextKey is the string you set in the config (see Custom Config below).

NOTE: This middleware uses our Storage package to support various databases through a single interface. The default configuration for this middleware saves data to memory, see the examples below for other databases.

Table of Contents

• CSRF Middleware
  • Table of Contents
  • Signatures
  • Examples
    • Default Config
    • Custom Config
    • Custom Storage/Database
    • Config
    • Default Config

Signatures

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

Examples

Import the middleware package that is part of the Fiber web framework

import (
  "github.com/gofiber/fiber/v2"
  "github.com/gofiber/fiber/v2/middleware/crsf"
)

After you initiate your Fiber app, you can use the following possibilities:

app.Use(csrf.New()) // Default config

Custom Config

app.Use(csrf.New(csrf.Config{
	KeyLookup:      "header:X-Csrf-Token",
	CookieName:     "csrf_",
	CookieSameSite: "Lax",
	Expiration:     1 * time.Hour,
	KeyGenerator:   utils.UUID,
	Extractor:      func(c *fiber.Ctx) (string, error) { ... },
}))

Note: KeyLookup will be ignored if Extractor is explicitly set.

Custom Storage/Database

You can use any storage from our storage package.

storage := sqlite3.New() // From github.com/gofiber/storage/sqlite3
app.Use(csrf.New(csrf.Config{
	Storage: storage,
}))

Config

// Config defines the config for middleware.
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_".
	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

	// Indicates if CSRF cookie is requested by SameSite.
	// 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

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

	// Context key to store generated CSRF token into context.
	// If left empty, token will not be stored in context.
	//
	// Optional. Default: ""
	ContextKey string

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

	// 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)
}

Default Config

var ConfigDefault = Config{
	KeyLookup:      "header:X-Csrf-Token",
	CookieName:     "csrf_",
	CookieSameSite: "Lax",
	Expiration:     1 * time.Hour,
	KeyGenerator:   utils.UUID,
}

Documentation

Index

• Constants
• Variables
• func CsrfFromCookie(param string) func(c *fiber.Ctx) (string, error)
• func CsrfFromForm(param string) func(c *fiber.Ctx) (string, error)
• func CsrfFromHeader(param string) func(c *fiber.Ctx) (string, error)
• func CsrfFromParam(param string) func(c *fiber.Ctx) (string, error)
• func CsrfFromQuery(param string) func(c *fiber.Ctx) (string, error)
• func New(config ...Config) fiber.Handler
• type Config

Constants

const HeaderName = "X-Csrf-Token"

Variables

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

ConfigDefault is the default config

Functions

func CsrfFromCookie

func CsrfFromCookie(param string) func(c *fiber.Ctx) (string, error)

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

func CsrfFromForm

func CsrfFromForm(param string) func(c *fiber.Ctx) (string, error)

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

func CsrfFromHeader

func CsrfFromHeader(param string) func(c *fiber.Ctx) (string, error)

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

func CsrfFromParam

func CsrfFromParam(param string) func(c *fiber.Ctx) (string, error)

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

func CsrfFromQuery

func CsrfFromQuery(param string) func(c *fiber.Ctx) (string, error)

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

func New

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

New creates a new middleware handler

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_".
	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

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

	// Context key to store generated CSRF token into context.
	// If left empty, token will not be stored in context.
	//
	// Optional. Default: ""
	ContextKey string

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

	// Deprecated: Please use Expiration
	CookieExpires time.Duration

	// Deprecated: Please use Cookie* related fields
	Cookie *fiber.Cookie

	// Deprecated: Please use KeyLookup
	TokenLookup 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.