feature: Support SameSite option (#123)

* Add SameSite with build constraied
* Update options test
* Fix after feedback
* Add docs

README.md

@@ -42,6 +42,7 @@ go get github.com/gorilla/csrf
 - [HTML Forms](#html-forms)
 - [JavaScript Apps](#javascript-applications)
 - [Google App Engine](#google-app-engine)
+- [Setting SameSite](#setting-samesite)
 - [Setting Options](#setting-options)
 
 gorilla/csrf is easy to use: add the middleware to your router with
@@ -267,6 +268,30 @@ Note: You can ignore this if you're using the
 [second-generation](https://cloud.google.com/appengine/docs/go/) Go runtime
 on App Engine (Go 1.11 and above).
 
+### Setting SameSite
+
+Go 1.11 introduced the option to set the SameSite attribute in cookies. This is
+valuable if a developer wants to instruct a browser to not include cookies during
+a cross site request. SameSiteStrictMode prevents all cross site requests from including
+the cookie. SameSiteLaxMode prevents CSRF prone requests (POST) from including the cookie
+but allows the cookie to be included in GET requests to support external linking.
+
+```go
+func main() {
+    CSRF := csrf.Protect(
+      []byte("a-32-byte-long-key-goes-here"),
+      // instruct the browser to never send cookies during cross site requests
+      csrf.SameSite(csrf.SameSiteStrictMode),
+    )
+
+    r := mux.NewRouter()
+    r.HandleFunc("/signup", GetSignupForm)
+    r.HandleFunc("/signup/post", PostSignupForm)
+
+    http.ListenAndServe(":8000", CSRF(r))
+}
+```
+
 ### Setting Options
 
 What about providing your own error handler and changing the HTTP header the
@@ -314,6 +339,9 @@ Getting CSRF protection right is important, so here's some background:
 - Cookies are authenticated and based on the [securecookie](https://github.com/gorilla/securecookie)
   library. They're also Secure (issued over HTTPS only) and are HttpOnly
   by default, because sane defaults are important.
+- Cookie SameSite attribute (prevents cookies from being sent by a browser
+  during cross site requests) are not set by default to maintain backwards compatibility
+  for legacy systems. The SameSite attribute can be set with the SameSite option.
 - Go's `crypto/rand` library is used to generate the 32 byte (256 bit) tokens
   and the one-time-pad used for masking them.
 

csrf.go

@@ -52,6 +52,22 @@ var (
 	ErrBadToken = errors.New("CSRF token invalid")
 )
 
+// SameSiteMode allows a server to define a cookie attribute making it impossible for
+// the browser to send this cookie along with cross-site requests. The main
+// goal is to mitigate the risk of cross-origin information leakage, and provide
+// some protection against cross-site request forgery attacks.
+//
+// See https://tools.ietf.org/html/draft-ietf-httpbis-cookie-same-site-00 for details.
+type SameSiteMode int
+
+// SameSite options
+const (
+	SameSiteDefaultMode SameSiteMode = iota + 1
+	SameSiteLaxMode
+	SameSiteStrictMode
+	SameSiteNoneMode
+)
+
 type csrf struct {
 	h    http.Handler
 	sc   *securecookie.SecureCookie
@@ -68,6 +84,7 @@ type options struct {
 	// http.Cookie field instead of the "correct" HTTPOnly name that golint suggests.
 	HttpOnly       bool
 	Secure         bool
+	SameSite       SameSiteMode
 	RequestHeader  string
 	FieldName      string
 	ErrorHandler   http.Handler
@@ -166,6 +183,7 @@ func Protect(authKey []byte, opts ...Option) func(http.Handler) http.Handler {
 				maxAge:   cs.opts.MaxAge,
 				secure:   cs.opts.Secure,
 				httpOnly: cs.opts.HttpOnly,
+				sameSite: cs.opts.SameSite,
 				path:     cs.opts.Path,
 				domain:   cs.opts.Domain,
 				sc:       cs.sc,

options.go

@@ -61,6 +61,26 @@ func HttpOnly(h bool) Option {
 	}
 }
 
+// SameSite sets the cookie SameSite attribute. Defaults to blank to maintain
+// backwards compatibility, however, Strict is recommended.
+//
+// SameSite(SameSiteStrictMode) will prevent the cookie from being sent by the
+// browser to the target site in all cross-site browsing context, even when
+// following a regular link (GET request).
+//
+// SameSite(SameSiteLaxMode) provides a reasonable balance between security and
+// usability for websites that want to maintain user's logged-in session after
+// the user arrives from an external link. The session cookie would be allowed
+// when following a regular link from an external website while blocking it in
+// CSRF-prone request methods (e.g. POST).
+//
+// This option is only available for go 1.11+.
+func SameSite(s SameSiteMode) Option {
+	return func(cs *csrf) {
+		cs.opts.SameSite = s
+	}
+}
+
 // 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
@@ -132,6 +152,9 @@ func parseOptions(h http.Handler, opts ...Option) *csrf {
 	cs.opts.Secure = true
 	cs.opts.HttpOnly = true
 
+	// Default to blank to maintain backwards compatibility
+	cs.opts.SameSite = SameSiteDefaultMode
+
 	// Default; only override this if the package user explicitly calls MaxAge(0)
 	cs.opts.MaxAge = defaultAge
 

options_test.go

@@ -24,6 +24,7 @@ func TestOptions(t *testing.T) {
 		Path(path),
 		HttpOnly(false),
 		Secure(false),
+		SameSite(SameSiteStrictMode),
 		RequestHeader(header),
 		FieldName(field),
 		ErrorHandler(http.HandlerFunc(errorHandler)),
@@ -53,6 +54,10 @@ func TestOptions(t *testing.T) {
 		t.Errorf("Secure not set correctly: got %v want %v", cs.opts.Secure, false)
 	}
 
+	if cs.opts.SameSite != SameSiteStrictMode {
+		t.Errorf("SameSite not set correctly: got %v want %v", cs.opts.SameSite, SameSiteStrictMode)
+	}
+
 	if cs.opts.RequestHeader != header {
 		t.Errorf("RequestHeader not set correctly: got %v want %v", cs.opts.RequestHeader, header)
 	}

store.go

@@ -1,3 +1,5 @@
+// +build go1.11
+
 package csrf
 
 import (
@@ -28,6 +30,7 @@ type cookieStore struct {
 	path     string
 	domain   string
 	sc       *securecookie.SecureCookie
+	sameSite SameSiteMode
 }
 
 // Get retrieves a CSRF token from the session cookie. It returns an empty token
@@ -63,6 +66,7 @@ func (cs *cookieStore) Save(token []byte, w http.ResponseWriter) error {
 		MaxAge:   cs.maxAge,
 		HttpOnly: cs.httpOnly,
 		Secure:   cs.secure,
+		SameSite: http.SameSite(cs.sameSite),
 		Path:     cs.path,
 		Domain:   cs.domain,
 	}

store_legacy.go

@@ -0,0 +1,86 @@
+// +build !go1.11
+// file for compatibility with go versions prior to 1.11
+
+package csrf
+
+import (
+	"net/http"
+	"time"
+
+	"github.com/gorilla/securecookie"
+)
+
+// store represents the session storage used for CSRF tokens.
+type store interface {
+	// Get returns the real CSRF token from the store.
+	Get(*http.Request) ([]byte, error)
+	// Save stores the real CSRF token in the store and writes a
+	// cookie to the http.ResponseWriter.
+	// For non-cookie stores, the cookie should contain a unique (256 bit) ID
+	// or key that references the token in the backend store.
+	// csrf.GenerateRandomBytes is a helper function for generating secure IDs.
+	Save(token []byte, w http.ResponseWriter) error
+}
+
+// cookieStore is a signed cookie session store for CSRF tokens.
+type cookieStore struct {
+	name     string
+	maxAge   int
+	secure   bool
+	httpOnly bool
+	path     string
+	domain   string
+	sc       *securecookie.SecureCookie
+	sameSite SameSiteMode
+}
+
+// Get retrieves a CSRF token from the session cookie. It returns an empty token
+// if decoding fails (e.g. HMAC validation fails or the named cookie doesn't exist).
+func (cs *cookieStore) Get(r *http.Request) ([]byte, error) {
+	// Retrieve the cookie from the request
+	cookie, err := r.Cookie(cs.name)
+	if err != nil {
+		return nil, err
+	}
+
+	token := make([]byte, tokenLength)
+	// Decode the HMAC authenticated cookie.
+	err = cs.sc.Decode(cs.name, cookie.Value, &token)
+	if err != nil {
+		return nil, err
+	}
+
+	return token, nil
+}
+
+// Save stores the CSRF token in the session cookie.
+func (cs *cookieStore) Save(token []byte, w http.ResponseWriter) error {
+	// Generate an encoded cookie value with the CSRF token.
+	encoded, err := cs.sc.Encode(cs.name, token)
+	if err != nil {
+		return err
+	}
+
+	cookie := &http.Cookie{
+		Name:     cs.name,
+		Value:    encoded,
+		MaxAge:   cs.maxAge,
+		HttpOnly: cs.httpOnly,
+		Secure:   cs.secure,
+		Path:     cs.path,
+		Domain:   cs.domain,
+	}
+
+	// Set the Expires field on the cookie based on the MaxAge
+	// If MaxAge <= 0, we don't set the Expires attribute, making the cookie
+	// session-only.
+	if cs.maxAge > 0 {
+		cookie.Expires = time.Now().Add(
+			time.Duration(cs.maxAge) * time.Second)
+	}
+
+	// Write the authenticated cookie to the response.
+	http.SetCookie(w, cookie)
+
+	return nil
+}