charlie

README

charlie

Charlie provides a fast, safe, stateless mechanism for adding CSRF protection to web applications.

For documentation, check godoc.

Documentation

Overview

Package charlie provides a fast, safe, stateless mechanism for adding CSRF protection to web applications.

Charlie generates per-request tokens, which resist modern web attacks like BEAST, BREACH, CRIME, TIME, and Lucky 13, as well as web attacks of the future, like CONDOR, BEETLEBUTT, NINJAFACE, and TacoTacoPopNLock Quasi-Chunking. In addition, the fact that Charlie tokens are stateless means their usage is dramatically simpler than most CSRF countermeasures--simply return a token with each response and require a token with each authenticated request.

A token is a 32-bit Unix epoch timestamp, concatenated with the HMAC-SHA256-128 MAC of both the timestamp and the user's identity (or session ID). This is a rapidly changing value, making tokens indistinguishable from random data to an attacker performing an online attack.

Generation and validation each take ~4us on modern hardware, and the tokens themselves are only 28 bytes long.

Example

// create a new TokenParams
params := New([]byte("yay for dumbledore"))

http.HandleFunc("/secure", func(w http.ResponseWriter, r *http.Request) {
	sessionID := r.Header.Get("Session-ID")

	// validate the token, if any
	token := r.Header.Get("CSRF-Token")
	if err := params.Validate(sessionID, token); err != nil {
		http.Error(w, "Invalid CSRF token", http.StatusBadRequest)
		return
	}

	// generate a new token for the response
	w.Header().Add("CSRF-Token", params.Generate(sessionID))

	// handle actual request
	// ...
})

Index

• Variables
• type HTTPParams
  • func (hp *HTTPParams) Wrap(h http.Handler) http.Handler
• type Params
  • func New(key []byte) *Params
  • func (p *Params) Generate(id string) string
  • func (p *Params) Validate(id, token string) error

Examples

• Package

Variables

var (
	// ErrInvalidToken is returned when the provided token is invalid.
	ErrInvalidToken = errors.New("invalid token")
)

Types

type HTTPParams

type HTTPParams struct {
	InvalidHandler http.Handler

	Key []byte

	CSRFCookie string
	CSRFHeader string

	SessionCookie string
	SessionHeader string
}

HTTPParams provides configuration for wrapping an http.Handler to check the validity of a CSRF token before permitting a request.

func (*HTTPParams) Wrap

func (hp *HTTPParams) Wrap(h http.Handler) http.Handler

Wrap wraps an http.Handler to check the validity of a CSRF token. It only serves requests where a valid ID/token pair can be found in either the request headers or cookies. Otherwise, it calls the InvalidHandler or returns an empty 403.

type Params

type Params struct {
	MaxAge time.Duration // MaxAge is the maximum age of tokens.
	// contains filtered or unexported fields
}

Params are the parameters used for generating and validating tokens.

func New

func New(key []byte) *Params

New returns a new set of parameters given a key.

func (*Params) Generate

func (p *Params) Generate(id string) string

Generate returns a new token for the given user.

func (*Params) Validate

func (p *Params) Validate(id, token string) error

Validate validates the given token for the given user.