csrfbanana

README

CSRFBanana

CSRF Protection for gorilla/sessions in the Go Language

CSRFBanana is a middleware package that helps prevent cross-site request forgery attacks. The package can generate tokens per session or per page. Tokens can also be regenerated after a successful or failed attempt to validate.

In this package, the CSRF tokens are stored in the (same) session cookie that is handled by gorilla/sessions. You can read about the different CSRF approaches on StackOverflow: Why is it common to put CSRF prevention tokens in cookies?

Usage

Import the package:

import "github.com/josephspurrier/csrfbanana"

Configure the package as middleware:

// Default handler
h := http.HandlerFunc(YourOwnDefaultFunction)

// Insert the CSRFBanana here to prevent CSRF
cs := csrfbanana.New(h, Store, SessionName)

// Set error page for CSRF failures
cs.FailureHandler(http.HandlerFunc(routeInvalidToken))

// Generate a new token after each success/failure (also prevents double submits)
cs.ClearAfterUsage(true)

// Exclude routes like /static/ from token generation/checking
cs.ExcludeRegexPaths([]string{"/static(.*)"})

// Set the token length (default is 32)
csrfbanana.TokenLength = 32

// Set the token name used in the forms and session (default is token)
csrfbanana.TokenName = "token"

// Set the token to generate per page (false - the default) or per session (true)
csrfbanana.SingleToken = false

// Pass the handler to your HTTP server
http.ListenAndServe(":80", cs)

Generate the token before passing to your templates:

// Create a map for the template
vars := make(map[string]string)

// Store the CSRF token to the map
vars["token"] = csrfbanana.Token(w, r, sess)

// Show the template
templ.Execute(w, vars)

Add the token to every POST form that is not excluded by ExcludeRegexPaths():

<input type="hidden" name="token" value="{{.token}}">

Note: Any other POST operation needs to either include the token or be added to ExcludeRegexPaths().

Working Example

To see the example in action, use the following commands:

go get github.com/josephspurrier/csrfbanana/example
go run src/github.com/josephspurrier/csrfbanana/example/example.go

Major Contributions

Thanks to Justinas Stankevičius for his CSRF package which I used as a solid example.

Documentation

Overview

Package csrfbanana creates a token to protect against CSRF attacks

Index

• Constants
• Variables
• func Clear(w http.ResponseWriter, r *http.Request, sess *sessions.Session)
• func Token(w http.ResponseWriter, r *http.Request, sess *sessions.Session) string
• func TokenWithPath(w http.ResponseWriter, r *http.Request, sess *sessions.Session, urlPath string) string
• type CSRFHandler
  • func New(next http.Handler, sessStore *sessions.CookieStore, sessName string) *CSRFHandler
  • func (h *CSRFHandler) ClearAfterUsage(bl bool)
  • func (h *CSRFHandler) ExcludeRegexPaths(strings []string)
  • func (h *CSRFHandler) FailureHandler(handler http.Handler)
  • func (h *CSRFHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type StringMap

Constants

const (
	// the HTTP status code for the default failure handler
	FailureCode = 400
)

Variables

var (
	TokenLength = 32      // Length of the token
	TokenName   = "token" // Name of the token in the session variables
	SingleToken = false   // True is one token for entire session, false is unique token for each URL
)

Functions

func Clear

func Clear(w http.ResponseWriter, r *http.Request, sess *sessions.Session)

Clear will remove all the tokens. Call after a permission change.

func Token

func Token(w http.ResponseWriter, r *http.Request, sess *sessions.Session) string

Token will return a token. If SingleToken = true, it will return the same token for every page.

func TokenWithPath

func TokenWithPath(w http.ResponseWriter, r *http.Request, sess *sessions.Session, urlPath string) string

Token will return a token for the specified URL. SingleToken is ignored.

Types

type CSRFHandler

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

CSRFHandler contains the configuration for the CSRF structure

func New

func New(next http.Handler, sessStore *sessions.CookieStore, sessName string) *CSRFHandler

New can be used as middleware because it returns an http.HandlerFunc

func (*CSRFHandler) ClearAfterUsage

func (h *CSRFHandler) ClearAfterUsage(bl bool)

RegenerateEveryRequest will regenerate a token everytime it's checked (prevents double submit problem)

func (*CSRFHandler) ExcludeRegexPaths

func (h *CSRFHandler) ExcludeRegexPaths(strings []string)

ExcludeRegexPath excludes a list of paths from the token middleware

func (*CSRFHandler) FailureHandler

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

FailureHandler sets the handler if the token check fails

func (*CSRFHandler) ServeHTTP

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

ServeHTTP will valid a token and it is does not match, it will show the FailureHandler

type StringMap

type StringMap map[string]string

StringMap has key of string and value of string