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 max number of tokens stored per session (default is 20)
csrfbanana.MaxTokens = 20

// 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().

Multiple Forms on the Same Page

To add tokens to multiple forms on the same page, use TokenWithPath() to specify the URL where the data will be submitted:

// Store token 1
vars["token1"] = csrfbanana.TokenWithPath(w, r, sess, "/form1")

// Store token 2
vars["token2"] = csrfbanana.TokenWithPath(w, r, sess, "/form2")

Then insert the tokens into the template:

<!-- Form 1 -->
<form method="post" action="/form1">
...
<input type="hidden" name="token" value="{{.token1}}">
</form>

<!-- Form 2 -->
<form method="post" action="/form2">
...
<input type="hidden" name="token" value="{{.token2}}">
</form>

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.Store, 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
	MaxTokens   = 20      // Maximum number of tokens saved in a session - prevents this error: Error saving session: securecookie: the value is too long
)

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.Store, 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