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
- http://www.cs.utexas.edu/~shmat/courses/cs378_spring09/zeller.pdf
- https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF)
- http://security.stackexchange.com/questions/91165/why-is-the-synchronizer-token-pattern-preferred-over-the-origin-header-check-to
- https://bugzilla.mozilla.org/show_bug.cgi?id=446344
- http://lists.webappsec.org/pipermail/websecurity_lists.webappsec.org/2011-February/007533.html
- http://stackoverflow.com/questions/24680302/csrf-protection-with-cors-origin-header-vs-csrf-token
- https://www.owasp.org/index.php/Testing_for_CSRF_(OTG-SESS-005)
- https://www.fastly.com/blog/caching-uncacheable-csrf-security
- 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 ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func 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 ¶
WithDomain configures the domain under which the CSRF cookie is going to be set.
func WithSecret ¶
WithSecret configures the secret cryptographic key for signing the token.
func WithUserID ¶
WithUserID allows to configure a random and unique user ID identifier used to generate the CSRF token.
Source Files