CSRF

Cross-site request forgery, also known as one-click attack or session riding and abbreviated as CSRF (sometimes pronounced sea-surf) or XSRF, is a type of malicious exploit of a website where unauthorized commands are transmitted from a user that the website trusts.

Usage

  1. e.Use(middleware.CSRF())

Custom Configuration

Usage

  1. e := echo.New()
  2. e.Use(middleware.CSRFWithConfig(middleware.CSRFConfig{
  3.   TokenLookup: "header:X-XSRF-TOKEN",
  4. }))

Example above uses X-XSRF-TOKEN request header to extract CSRF token.

Example Configuration that reads token from Cookie

  1. middleware.CSRFWithConfig(middleware.CSRFConfig{
  2.     TokenLookup:    "cookie:_csrf",
  3.     CookiePath:     "/",
  4.     CookieDomain:   "example.com",
  5.     CookieSecure:   true,
  6.     CookieHTTPOnly: true,
  7.     CookieSameSite: http.SameSiteStrictMode,
  8. })

Accessing CSRF Token

Server-side

CSRF token can be accessed from Echo#Context using ContextKey and passed to the client via template.

Client-side

CSRF token can be accessed from CSRF cookie.

Configuration

  1. CSRFConfig struct {
  2.   // Skipper defines a function to skip middleware.
  3.   Skipper Skipper
  5.   // TokenLength is the length of the generated token.
  6.   TokenLength uint8 `json:"token_length"`
  7.   // Optional. Default value 32.
  9.   // TokenLookup is a string in the form of "<source>:<key>" that is used
  10.   // to extract token from the request.
  11.   // Optional. Default value "header:X-CSRF-Token".
  12.   // Possible values:
  13.   // - "header:<name>"
  14.   // - "form:<name>"
  15.   // - "query:<name>"
  16.   // - "cookie:<name>"
  17.   TokenLookup string `json:"token_lookup"`
  19.   // Context key to store generated CSRF token into context.
  20.   // Optional. Default value "csrf".
  21.   ContextKey string `json:"context_key"`
  23.   // Name of the CSRF cookie. This cookie will store CSRF token.
  24.   // Optional. Default value "_csrf".
  25.   CookieName string `json:"cookie_name"`
  27.   // Domain of the CSRF cookie.
  28.   // Optional. Default value none.
  29.   CookieDomain string `json:"cookie_domain"`
  31.   // Path of the CSRF cookie.
  32.   // Optional. Default value none.
  33.   CookiePath string `json:"cookie_path"`
  35.   // Max age (in seconds) of the CSRF cookie.
  36.   // Optional. Default value 86400 (24hr).
  37.   CookieMaxAge int `json:"cookie_max_age"`
  39.   // Indicates if CSRF cookie is secure.
  40.   // Optional. Default value false.
  41.   CookieSecure bool `json:"cookie_secure"`
  43.   // Indicates if CSRF cookie is HTTP only.
  44.   // Optional. Default value false.
  45.   CookieHTTPOnly bool `json:"cookie_http_only"`
  46. }

Default Configuration

  1. DefaultCSRFConfig = CSRFConfig{
  2.   Skipper:      DefaultSkipper,
  3.   TokenLength:  32,
  4.   TokenLookup:  "header:" + echo.HeaderXCSRFToken,
  5.   ContextKey:   "csrf",
  6.   CookieName:   "_csrf",
  7.   CookieMaxAge: 86400,
  8. }