csrf

README

goji/ctx-csrf

ctx-csrf is a HTTP middleware library that provides cross-site request forgery (CSRF) protection with support for Go's net/context package. It includes:

• The csrf.Protect middleware/handler that can be used with goji.Use to provide CSRF protection on routes attached to a router or a sub-router.
• A csrf.Token function that provides the token to pass into your response, whether that be a HTML form or a JSON response body.
• ... and a csrf.TemplateField helper that you can pass into your html/template templates to replace a {{ .csrfField }} template tag with a hidden input field.

This library is designed to work with not just the the Goji micro-framework, but any project that satisfies the goji.Handler interface: ServeHTTPC(context.Context, http.ResponseWriter, *http.Request).

This makes it compatible with other parts of the Go ecosystem. The context.Context request context doesn't rely on a global map, and is therefore free from contention in a busy web service.

The library also assumes HTTPS by default: sending cookies over vanilla HTTP is risky and you're likely to get hurt.

Note: If you're using Goji v1, the older goji/csrf still exists.

Examples

ctx-csrf is easy to use: add the middleware to your stack with the below:

goji.UseC(csrf.Protect([]byte("32-byte-long-auth-key")))

... and then collect the token with csrf.Token(c, r) before passing it to the template, JSON body or HTTP header (you pick!). ctx-csrf inspects HTTP headers (first) and the form body (second) on subsequent POST/PUT/PATCH/DELETE/etc. requests for the token.

HTML Forms

Here's the common use-case: HTML forms you want to provide CSRF protection for, in order to protect malicious POST requests being made:

package main

import (
    "html/template"
    "net/http"

    "goji.io"
    "github.com/goji/ctx-csrf"
    "github.com/zenazn/goji/graceful"
)

func main() {
    m := goji.NewMux()
    // Add the middleware to your router.
    // PS: Don't forget to pass csrf.Secure(false) if you're developing locally
    // over plain HTTP (just don't leave it on in production).
    m.UseC(csrf.Protect([]byte("32-byte-long-auth-key")))
    m.HandleFuncC(pat.Get("/signup"), ShowSignupForm)
    // POST requests without a valid token will return a HTTP 403 Forbidden.
    m.HandleFuncC(pat.Post("/signup/post"), SubmitSignupForm)

    graceful.ListenAndServe(":8000", m)
}

func ShowSignupForm(ctx context.Context, w http.ResponseWriter, r *http.Request) {
    // signup_form.tmpl just needs a {{ .csrfField }} template tag for
    // csrf.TemplateField to inject the CSRF token into. Easy!
    t.ExecuteTemplate(w, "signup_form.tmpl", map[string]interface{
        csrf.TemplateTag: csrf.TemplateField(ctx, r),
    })
    // We could also retrieve the token directly from csrf.Token(c, r) and 
    // set it in the request header - w.Header.Set("X-CSRF-Token", token)
    // This is useful if your sending JSON to clients or a front-end JavaScript
    // framework.
}

func SubmitSignupForm(ctx context.Context, w http.ResponseWriter, r *http.Request) {
    // We can trust that requests making it this far have satisfied
    // our CSRF protection requirements.
}

JSON Responses

This approach is useful if you're using a front-end JavaScript framework like Ember or Angular, or are providing a JSON API.

We'll also look at applying selective CSRF protection using Goji's sub-routers, as we don't handle any POST/PUT/DELETE requests with our top-level router.

package main

import (
    "goji.io"
    "github.com/goji/ctx-csrf"
    "github.com/zenazn/goji/graceful"
)

func main() {
    m := goji.NewMux()
    // Our top-level router doesn't need CSRF protection: it's simple.
    m.HandleFuncC(pat.Get("/"), ShowIndex)

    api := goji.NewMux()
    m.HandleC("/api/*", api)
    // ... but our /api/* routes do, so we add it to the sub-router only.
    api.UseC(csrf.Protect([]byte("32-byte-long-auth-key")))

    api.Get("/api/user/:id", GetUser)
    api.Post("/api/user", PostUser)

    graceful.ListenAndServe(":8000", m)
}

func GetUser(ctx context.Context, w http.ResponseWriter, r *http.Request) {
    // Authenticate the request, get the :id from the route params, 
    // and fetch the user from the DB, etc.

    // Get the token and pass it in the CSRF header. Our JSON-speaking client 
    // or JavaScript framework can now read the header and return the token in 
    // in its own "X-CSRF-Token" request header on the subsequent POST.
    w.Header().Set("X-CSRF-Token", csrf.Token(ctx, r))
    b, err := json.Marshal(user)
    if err != nil {
        http.Error(w, http.StatusText(500), 500)
        return
    }

    w.Write(b)
}

Setting Options

What about providing your own error handler and changing the HTTP header the package inspects on requests? (i.e. an existing API you're porting to Go). Well, ctx-csrf provides options for changing these as you see fit:

func main() {
    m := goji.NewMux()
    CSRF := csrf.Protect(
            []byte("a-32-byte-long-key-goes-here"),
            csrf.RequestHeader("Authenticity-Token"),
            csrf.FieldName("authenticity_token"),
            // Note that csrf.ErrorHandler takes a Goji goji.Handler type, else
            // your error handler can't retrieve the error reason from the
            // context.
            // The signature `func UnauthHandler(ctx context.Context, w http.ResponseWriter, r *http.Request)`
            // is a goji.Handler, and the simplest to use if you'd like to serve
            // "pretty" error pages (who doesn't?).
            csrf.ErrorHandler(goji.HandlerFunc(serverError(403))),
        )

    m.UseC(CSRF)
    m.HandleFuncC(pat.Get("/signup"), GetSignupForm)
    m.HandleFuncC(pat.Post("/signup"), PostSignupForm)

    graceful.ListenAndServe(":8000", m)
}

Not too bad, right?

If there's something you're confused about or a feature you would like to see added, open an issue with your code so far.

Design Notes

Getting CSRF protection right is important, so here's some background:

• This library generates unique-per-request (masked) tokens as a mitigation against the BREACH attack.
• The 'base' (unmasked) token is stored in the session, which means that multiple browser tabs won't cause a user problems as their per-request token is compared with the base token.
• Operates on a "whitelist only" approach where safe (non-mutating) HTTP methods (GET, HEAD, OPTIONS, TRACE) are the only methods where token validation is not enforced.
• The design is based on the battle-tested Django and Ruby on Rails approaches.
• Cookies are authenticated and based on the securecookie library. They're also Secure (issued over HTTPS only) and are HttpOnly by default, because sane defaults are important.
• Go's crypto/rand library is used to generate the 32 byte (256 bit) tokens and the one-time-pad used for masking them.

This library does not seek to be adventurous.

License

BSD licensed. See the LICENSE file for details.

Documentation

Overview

Package csrf (goji/csrf) provides Cross Site Request Forgery protection middleware for the Goji microframework (https://goji.io).

Index

• Variables
• func FailureReason(ctx context.Context, r *http.Request) error
• func Protect(authKey []byte, opts ...Option) func(http.Handler) http.Handler
• func TemplateField(ctx context.Context, r *http.Request) template.HTML
• func Token(ctx context.Context, r *http.Request) string
• func UnsafeSkipCheck(ctx context.Context) context.Context
• type Option
  • func CookieName(name string) Option
  • func Domain(domain string) Option
  • func ErrorHandler(h http.Handler) Option
  • func FieldName(name string) Option
  • func HttpOnly(h bool) Option
  • func MaxAge(age int) Option
  • func Path(p string) Option
  • func RequestHeader(header string) Option
  • func Secure(s bool) Option

Variables

var (
	// ErrNoReferer is returned when a HTTPS request provides an empty Referer
	// header.
	ErrNoReferer = errors.New("referer not supplied")
	// ErrBadReferer is returned when the scheme & host in the URL do not match
	// the supplied Referer header.
	ErrBadReferer = errors.New("referer invalid")
	// ErrNoToken is returned if no CSRF token is supplied in the request.
	ErrNoToken = errors.New("CSRF token not found in request")
	// ErrBadToken is returned if the CSRF token in the request does not match
	// the token in the session, or is otherwise malformed.
	ErrBadToken = errors.New("CSRF token invalid")
)

var TemplateTag = "csrfField"

TemplateTag provides a default template tag - e.g. {{ .csrfField }} - for use with the TemplateField function.

Functions

func FailureReason

func FailureReason(ctx context.Context, r *http.Request) error

FailureReason makes CSRF validation errors available in the request context. This is useful when you want to log the cause of the error or report it to client.

func Protect

func Protect(authKey []byte, opts ...Option) func(http.Handler) http.Handler

Protect is HTTP middleware that provides Cross-Site Request Forgery protection.

It securely generates a masked (unique-per-request) token that can be embedded in the HTTP response (e.g. form field or HTTP header). The original (unmasked) token is stored in the session, which is inaccessible by an attacker (provided you are using HTTPS). Subsequent requests are expected to include this token, which is compared against the session token. Requests that do not provide a matching token are served with a HTTP 403 'Forbidden' error response.

Example:

package main

import (
    "html/template"
    "net/http"

    "goji.io"
    "github.com/goji/ctx-csrf"
    "github.com/zenazn/goji/graceful"
)

func main() {
    m := goji.NewMux()
    // Add the middleware to your router.
    m.UseC(csrf.Protect([]byte("32-byte-long-auth-key")))
    m.HandleFuncC(pat.Get("/signup"), ShowSignupForm)
    // POST requests without a valid token will return a HTTP 403 Forbidden.
    m.HandleFuncC(pat.Post("/signup/post"), SubmitSignupForm)

    graceful.ListenAndServe(":8000", m)
}

func ShowSignupForm(ctx context.Context, w http.ResponseWriter, r *http.Request) {
    // signup_form.tmpl just needs a {{ .csrfField }} template tag for
    // csrf.TemplateField to inject the CSRF token into. Easy!
    t.ExecuteTemplate(w, "signup_form.tmpl", map[string]interface{
        csrf.TemplateTag: csrf.TemplateField(ctx, r),
    })
    // We could also retrieve the token directly from csrf.Token(c, r) and
    // set it in the request header - w.Header.Set("X-CSRF-Token", token)
    // This is useful if your sending JSON to clients or a front-end JavaScript
    // framework.
}

func SubmitSignupForm(ctx context.Context, w http.ResponseWriter, r *http.Request) {
    // We can trust that requests making it this far have satisfied
    // our CSRF protection requirements.
}

func TemplateField

func TemplateField(ctx context.Context, r *http.Request) template.HTML

TemplateField is a template helper for html/template that provides an <input> field populated with a CSRF token.

Example:

// The following tag in our form.tmpl template:
{{ .csrfField }}

// ... becomes:
<input type="hidden" name="goji.csrf.Token" value="<token>">

func Token

func Token(ctx context.Context, r *http.Request) string

Token returns a masked CSRF token ready for passing into HTML template or a JSON response body. An empty token will be returned if the middleware has not been applied (which will fail subsequent validation).

func UnsafeSkipCheck

func UnsafeSkipCheck(ctx context.Context) context.Context

UnsafeSkipCheck will skip the CSRF check for any requests using the provided context.Context. This must be called before the CSRF middleware.

Note: You should not set this without otherwise securing the request from CSRF attacks. The primary use-case for this function is to turn off CSRF checks for non-browser clients using authorization tokens against your API.

Types

type Option

type Option func(*csrf) error

Option describes a functional option for configuring the CSRF handler.

func CookieName

func CookieName(name string) Option

CookieName changes the name of the CSRF cookie issued to clients.

Note that cookie names should not contain whitespace, commas, semicolons, backslashes or control characters as per RFC6265.

func Domain

func Domain(domain string) Option

Domain sets the cookie domain. Defaults to the current domain of the request only (recommended).

This should be a hostname and not a URL. If set, the domain is treated as being prefixed with a '.' - e.g. "example.com" becomes ".example.com" and matches "www.example.com" and "secure.example.com".

func ErrorHandler

func ErrorHandler(h http.Handler) Option

ErrorHandler allows you to change the handler called when CSRF request processing encounters an invalid token or request. A typical use would be to provide a handler that returns a static HTML file with a HTTP 403 status. By default a HTTP 403 status and a plain text CSRF failure reason are served.

Note that a custom error handler can also access the csrf.Failure(c, r) function to retrieve the CSRF validation reason from Goji's request context.

func FieldName

func FieldName(name string) Option

FieldName allows you to change the name value of the hidden <input> field generated by csrf.TemplateField. The default is {{ .csrfToken }}

func HttpOnly

func HttpOnly(h bool) Option

HttpOnly sets the 'HttpOnly' flag on the cookie. Defaults to true (recommended).

func MaxAge

func MaxAge(age int) Option

MaxAge sets the maximum age (in seconds) of a CSRF token's underlying cookie. Defaults to 12 hours.

func Path

func Path(p string) Option

Path sets the cookie path. Defaults to the path the cookie was issued from (recommended).

This instructs clients to only respond with cookie for that path and its subpaths - i.e. a cookie issued from "/register" would be included in requests to "/register/step2" and "/register/submit".

func RequestHeader

func RequestHeader(header string) Option

RequestHeader allows you to change the request header the CSRF middleware inspects. The default is X-CSRF-Token.

func Secure

func Secure(s bool) Option

Secure sets the 'Secure' flag on the cookie. Defaults to true (recommended). Set this to 'false' in your development environment otherwise the cookie won't be sent over an insecure channel. Setting this via the presence of a 'DEV' environmental variable is a good way of making sure this won't make it to a production environment.