csrf

README

csrf

Middleware csrf generates and validates CSRF tokens for Macaron.

API Reference

Installation

go get gitea.com/macaron/csrf

Getting Help

• API Reference
• Documentation

License

This project is under the Apache License, Version 2.0. See the LICENSE file for the full license text.

Documentation

Overview

Package csrf is a middleware that generates and validates CSRF tokens for Macaron.

Index

• Constants
• func Csrfer(options ...Options) macaron.Handler
• func Generate(options ...Options) macaron.Handler
• func GenerateToken(key, userID, actionID string) string
• func ValidToken(token, key, userID, actionID string) bool
• func Validate(ctx *macaron.Context, x CSRF)
• func Version() string
• type CSRF
• type Options

Constants

const TIMEOUT = 24 * time.Hour

The duration that XSRF tokens are valid. It is exported so clients may set cookie timeouts that match generated tokens.

Functions

func Csrfer

func Csrfer(options ...Options) macaron.Handler

Csrfer 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 Generate

func Generate(options ...Options) macaron.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 GenerateToken

func GenerateToken(key, userID, actionID string) string

GenerateToken returns a URL-safe secure XSRF token that expires in 24 hours.

key is a secret key for your application. userID is a unique identifier for the user. actionID is the action the user is taking (e.g. POSTing to a particular path).

func ValidToken

func ValidToken(token, key, userID, actionID string) bool

Valid returns true if token is a valid, unexpired token returned by Generate.

func Validate

func Validate(ctx *macaron.Context, 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.

func Version

func Version() string

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 cookie path
	GetCookiePath() string
	// Return the flag value used for the csrf token.
	GetCookieHttpOnly() bool
	// 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 represents a CSRF service and 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
	// Cookie domain.
	CookieDomain string
	// Cookie path.
	CookiePath     string
	CookieHttpOnly bool
	// SameSite set the cookie SameSite type
	SameSite http.SameSite
	// 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
	// Disallow Origin appear in request header.
	Origin bool
	// The function called when Validate fails.
	ErrorFunc func(w http.ResponseWriter)
	// Cookie life time. Default is 0
	CookieLifeTime int
	// contains filtered or unexported fields
}

Options maintains options to manage behavior of Generate.