csrf

README

csrf

Martini cross-site request forgery protection middlware.

API Reference

Usage

package main

import (
	"github.com/go-martini/martini"
	"github.com/martini-contib/csrf"
	"github.com/martini-contib/sessions"
	"github.com/martini-contrib/render"
	"net/http"
)

func main() {
	m := martini.Classic()
	store := sessions.NewCookieStore([]byte("secret123"))
	m.Use(sessions.Sessions("my_session", store))
	// Setup generation middleware.
	m.Use(csrf.Generate(&csrf.Options{
		Secret:     "token123",
		SessionKey: "userID",
		// Custom error response.
		ErrorFunc: func(w http.ResponseWriter) {
			http.Error(w, "CSRF token validation failed", http.StatusBadRequest)
		}
	}))
	m.Use(render.Renderer())

	// Simulate the authentication of a session. If userID exists redirect
	// to a form that requires csrf protection.
	m.Get("/", func(s sessions.Session, r render.Render) {
		if s.Get("userID") == nil {
			r.Redirect("/login", 302)
			return
		}
		r.Redirect("/protected", 302)
	})

	// Set userID for the session.
	m.Get("/login", func(s sessions.Session, r render.Render) {
		s.Set("userID", "123456")
		r.Redirect("/", 302)
	})

	// Render a protected form. Passing a csrf token by calling x.GetToken()
	m.Get("/protected", func(s sessions.Session, r render.Render, x csrf.CSRF) {
		if s.Get("userID") == nil {
			r.Redirect("/login", 401)
			return
		}
		// Pass token to the protected template.
		r.HTML(200, "protected", x.GetToken())
	})

	// Apply csrf validation to route.
	m.Post("/protected", csrf.Validate, func(s sessions.Session, r render.Render) {
		if s.Get("userID") != nil {
			r.HTML(200, "result", "You submitted a valid token")
			return
		}
		r.Redirect("/login", 401)
	})

	m.Run()
}

Security

Applications using the method package should also validate PATCH, PUT, and DELETE requests.

Authors

• Tom Steele

Documentation

Overview

Package csrf generates and validates csrf tokens for martini. There are multiple methods of delivery including via a cookie or HTTP header. Validation occurs via a traditional hidden form key of "_csrf", or via a custom HTTP header "X-CSRFToken".

package main

import (

"github.com/go-martini/martini"
"github.com/martini-contib/csrf"
"github.com/martini-contrib/render"
"github.com/martini-contib/sessions"
"net/http"

)

func main() {
    m := martini.Classic()
    store := sessions.NewCookieStore([]byte("secret123"))
    m.Use(sessions.Sessions("my_session", store))
    // Setup generation middleware.
    m.Use(csrf.Generate(&csrf.Options{
        Secret:     "token123",
        SessionKey: "userID",
    }))
    m.Use(render.Renderer())

    // Simulate the authentication of a session. If userID exists redirect
    // to a form that requires csrf protection.
    m.Get("/", func(s sessions.Session, r render.Render) {
        if s.Get("userID") == nil {
            r.Redirect("/login", 302)
            return
        }
        r.Redirect("/protected", 302)
    })

    // Set userID for the session.
    m.Get("/login", func(s sessions.Session, r render.Render) {
        s.Set("userID", "123456")
        r.Redirect("/", 302)
    })

    // Render a protected form. Passing a csrf token by calling x.GetToken()
    m.Get("/protected", func(s sessions.Session, r render.Render, x csrf.CSRF) {
        if s.Get("userID") == nil {
            r.Redirect("/login", 401)
            return
        }
        r.HTML(200, "protected", x.GetToken())
    })

    // Apply csrf validation to route.
    m.Post("/protected", csrf.Validate, func(s sessions.Session, r render.Render) {
        if s.Get("userID") != nil {
            r.HTML(200, "result", "You submitted a valid token")
            return
        }
        r.Redirect("/login", 401)
    })

    m.Run()
}

Index

• func Generate(opts *Options) martini.Handler
• func Validate(r *http.Request, w http.ResponseWriter, x CSRF)
• type CSRF
• type Options

Functions

func Generate

func Generate(opts *Options) martini.Handler

Generate maps CSRF to each request. If this request is a Get request, it will generate a new token. Additionally, depending on options set, generated tokens will be sent via Header and/or Cookie.

func Validate

func Validate(r *http.Request, w http.ResponseWriter, x CSRF)

Validate should be used as a per route middleware. It attempts to get a token from a "X-CSRFToken" HTTP header and then a "_csrf" form value. If one of these is found, the token will be validated using ValidToken. If this validation fails, custom Error is sent in the reply. If neither a header or form value is found, http.StatusBadRequest is sent.

Types

type CSRF

type CSRF interface {
	// Return HTTP header to search for token.
	GetHeaderName() string
	// Return form value to search for token.
	GetFormName() string
	// Return cookie name to search for token.
	GetCookieName() string
	// Return the token.
	GetToken() string
	// Validate by token.
	ValidToken(t string) bool
	// Error replies to the request with a custom function when ValidToken fails.
	Error(w http.ResponseWriter)
}

CSRF is used to get the current token and validate a suspect token.

type Options

type Options struct {
	// The global secret value used to generate Tokens.
	Secret string
	// HTTP header used to set and get token.
	Header string
	// Form value used to set and get token.
	Form string
	// Cookie value used to set and get token.
	Cookie string
	// Key used for getting the unique ID per user.
	SessionKey string
	// If true, send token via X-CSRFToken header.
	SetHeader bool
	// If true, send token via _csrf cookie.
	SetCookie bool
	// Set the Secure flag to true on the cookie.
	Secure bool
	// The function called when Validate fails.
	ErrorFunc func(w http.ResponseWriter)
}

Options maintains options to manage behavior of Generate.