csrf

README

CSRF handler

Offers stateless protection against CSRF attacks for Go web applications.

• Checks Origin header was sent and matches the Host header.
• Falls back to a URL-safe and secure HMAC token stored in a HTTP-only and secured cookie.
• Protects all HTTP requests that would potentially mutate data: POST, PUT, DELETE and PATCH.
• If you use CORS, make sure to enable Access-Control-Allow-Credentials, so that the cookie containing the HMAC token is sent to your backend service and can be verified by this handler.
• Allows content to be cacheable by CDNs as the token is sent in a cookie and not on the HTML document.

Assumptions

• HTTP Origin header is the best way to deflect CSRF attacks, though, some old browsers may not support it, therefore we provide a fallback to stateless HMAC tokens.
• TLS everywhere has been made possible by https://letsencrypt.org, so this handler only sends the CSRF cookie over TLS.
• Synchronizer Token Pattern is another way of protection, however, this handler offers a simpler and equally effective protection.
• This handler depends on a session or user ID, so you must implement the Session interface to allow the handler to retrieve the session ID from wherever it is being stored.

Further hardening

To make things a bit more difficult to malicious folks, take a look at defining your own Content Security Policy

References

1. http://www.cs.utexas.edu/~shmat/courses/cs378_spring09/zeller.pdf
2. https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF)
3. http://security.stackexchange.com/questions/91165/why-is-the-synchronizer-token-pattern-preferred-over-the-origin-header-check-to
4. https://bugzilla.mozilla.org/show_bug.cgi?id=446344
5. http://lists.webappsec.org/pipermail/websecurity_lists.webappsec.org/2011-February/007533.html
6. http://stackoverflow.com/questions/24680302/csrf-protection-with-cors-origin-header-vs-csrf-token
7. https://www.owasp.org/index.php/Testing_for_CSRF_(OTG-SESS-005)
8. https://www.fastly.com/blog/caching-uncacheable-csrf-security
9. http://stackoverflow.com/questions/2870371/why-is-jquerys-ajax-method-not-sending-my-session-cookie

Documentation

Overview

Package csrf offers stateless protection against CSRF attacks using the HTTP Origin header and falling back to HMAC tokens stored on secured and HTTP-only cookies.

Index

• func Handler(h http.Handler, opts ...Option) http.Handler
• type Option
  • func WithDomain(d string) Option
  • func WithName(n string) Option
  • func WithSecret(s string) Option
  • func WithUserID(s string) Option

Examples

• Handler

Functions

func Handler

func Handler(h http.Handler, opts ...Option) http.Handler

Handler checks Origin header first, if not set or has value "null" it validates using a HMAC CSRF token. For enabling Single Page Applications to send the XSRF cookie using async HTTP requests, use CORS and make sure Access-Control-Allow-Credential is enabled.

Example

package main

import (
	"fmt"
	"net/http"

	"github.com/c4milo/handlers/csrf"
)

func main() {
	mux := http.DefaultServeMux
	mux.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
		// The "/" pattern matches everything, so we need to check
		// that we're at the root here.
		if req.URL.Path != "/" {
			http.NotFound(w, req)
			return
		}
		fmt.Fprintf(w, "Welcome to the home page!")
	})

	opts := []csrf.Option{
		csrf.WithUserID("user ID"),
		csrf.WithSecret("my secret!"),
	}

	rack := csrf.Handler(mux, opts...)

	http.ListenAndServe(":8080", rack)
}

Types

type Option

type Option func(*handler)

Option implements http://commandcenter.blogspot.com/2014/01/self-referential-functions-and-design.html

func WithDomain

func WithDomain(d string) Option

WithDomain configures the domain under which the CSRF cookie is going to be set.

func WithName

func WithName(n string) Option

WithName allows configuring the CSRF cookie name.

func WithSecret

func WithSecret(s string) Option

WithSecret configures the secret cryptographic key for signing the token.

func WithUserID

func WithUserID(s string) Option

WithUserID allows to configure a random and unique user ID identifier used to generate the CSRF token.