csrf – github.com/gorilla/csrf Index | Files

package csrf

import "github.com/gorilla/csrf"

Package csrf (gorilla/csrf) provides Cross Site Request Forgery (CSRF) prevention middleware for Go web applications & services.

It includes:

gorilla/csrf is easy to use: add the middleware to individual handlers with the below: 

CSRF := csrf.Protect([]byte("32-byte-long-auth-key"))
http.HandlerFunc("/route", CSRF(YourHandler))

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

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 (
	"fmt"
	"html/template"
	"net/http"

	"github.com/gorilla/csrf"
	"github.com/gorilla/mux"
)

var form = `
<html>
<head>
<title>Sign Up!</title>
</head>
<body>
<form method="POST" action="/signup/post" accept-charset="UTF-8">
<input type="text" name="name">
<input type="text" name="email">
<!--
    The default template tag used by the CSRF middleware .
    This will be replaced with a hidden <input> field containing the
    masked CSRF token.
-->
{{ .csrfField }}
<input type="submit" value="Sign up!">
</form>
</body>
</html>
`

var t = template.Must(template.New("signup_form.tmpl").Parse(form))

func main() {
	r := mux.NewRouter()
	r.HandleFunc("/signup", ShowSignupForm)
	// All POST requests without a valid token will return HTTP 403 Forbidden.
	r.HandleFunc("/signup/post", SubmitSignupForm)

	// Add the middleware to your router by wrapping it.
	http.ListenAndServe(":8000",
		csrf.Protect([]byte("32-byte-long-auth-key"))(r))
}

func ShowSignupForm(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(r),
	})
}

func SubmitSignupForm(w http.ResponseWriter, r *http.Request) {
	// We can trust that requests making it this far have satisfied
	// our CSRF protection requirements.
	fmt.Fprintf(w, "%v\n", r.PostForm)
}

You can also send the CSRF token in the response header. This approach is useful if you're using a front-end JavaScript framework like Ember or Angular, or are providing a JSON API: 

package main

import (
    "github.com/gorilla/csrf"
    "github.com/gorilla/mux"
)

func main() {
    r := mux.NewRouter()

    api := r.PathPrefix("/api").Subrouter()
    api.HandleFunc("/user/:id", GetUser).Methods("GET")

    http.ListenAndServe(":8000",
        csrf.Protect([]byte("32-byte-long-auth-key"))(r))
}

func GetUser(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(r))
    b, err := json.Marshal(user)
    if err != nil {
        http.Error(w, err.Error(), 500)
        return
    }

    w.Write(b)
}

In addition: getting CSRF protection right is important, so here's some background:

This library does not seek to be adventurous.

Index

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 Domain 

func Domain(domain string) func(*csrf)

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) func(*csrf)

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 404 status and a plain text CSRF failure reason are served.

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

func FailureReason 

func FailureReason(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 FieldName 

func FieldName(name string) func(*csrf)

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

func HttpOnly 

func HttpOnly(h bool) func(*csrf)

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

func MaxAge 

func MaxAge(age int) func(*csrf)

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

func Path 

func Path(p string) func(*csrf)

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 Protect 

func Protect(authKey []byte, opts ...func(*csrf)) 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 (
	"github.com/elithrar/protect"
	"github.com/gorilla/mux"
)

func main() {
  r := mux.NewRouter()

  mux.HandlerFunc("/signup", GetSignupForm)
  // POST requests without a valid token will return a HTTP 403 Forbidden.
  mux.HandlerFunc("/signup/post", PostSignupForm)

  // Add the middleware to your router.
  http.ListenAndServe(":8000",
		  csrf.Protect([]byte("32-byte-long-auth-key"))(r))
}

func GetSignupForm(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(r),
	})
	// We could also retrieve the token directly from csrf.Token(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 RequestHeader 

func RequestHeader(header string) func(*csrf)

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

func Secure 

func Secure(s bool) func(*csrf)

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

func TemplateField 

func TemplateField(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="protect.csrf.Token" value="<token>">

func Token 

func Token(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).

Source Files

csrf.go doc.go helpers.go options.go store.go

Version
v1.0.1
Published
Aug 5, 2015
Platform
darwin/amd64
Imports
11 packages
Last checked
3 seconds ago –

Tools for package owners.