nosurf

https://pkg.go.dev/github.com/justinas/nosurf
Admin
nosurf is an HTTP middleware package for Go that prevents Cross-Site Request Forgery attacks by...
Tokens:3,983
Snippets:40
Trust Score:9.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### Example: Using SetIsTLSFunc with a reverse proxy

Source: https://pkg.go.dev/github.com/justinas/nosurf

Example of setting the IsTLSFunc to check the 'X-Forwarded-Proto' header and trusted proxy IPs, suitable when behind a TLS-terminating reverse proxy.

```go
var trustedProxies = []string{"198.51.100.1", "198.51.100.2"}
h.SetIsTLSFunc(func(r *http.Request) {
	ip, _, _ := strings.Cut(r.RemoteAddr, ":")
	proto := r.Header.Get("X-Forwarded-Proto")
	return slices.Contains(trustedProxies, ip) && proto == "https"
})
```

--------------------------------

### Example: Configure Allowed Origins

Source: https://pkg.go.dev/github.com/justinas/nosurf

Demonstrates how to use StaticOrigins to set allowed origins for CSRF checks.

```go
h := nosurf.New()
origins, err := nosurf.StaticOrigins("https://api.example.com", "http://insecure.example.com")
if err != nil {
	panic(err)
}
h.SetIsAllowedOriginFunc(origins)
```

--------------------------------

### Example: Using SetIsTLSFunc with Go's TLS stack

Source: https://pkg.go.dev/github.com/justinas/nosurf

Example of setting the IsTLSFunc to check if the request has TLS information, suitable when not using a TLS-terminating reverse proxy.

```go
h.SetIsTLSFunc(func(r *http.Request) bool { return r.TLS != nil })
```

--------------------------------

### Basic CSRF Protection with nosurf

Source: https://pkg.go.dev/github.com/justinas/nosurf

Integrate nosurf into your Go HTTP application to protect against CSRF attacks. This example shows how to wrap a handler with nosurf.New() and includes a basic HTML form with a CSRF token.

```go
package main

import (
	"fmt"
	"github.com/justinas/nosurf"
	"html/template"
	"net/http"
)

var templateString string = `
<!doctype html>
<html>
<body>
{{ if .name }}
<p>Your name: {{ .name }}</p>
{{ end }}
<form action="/" method="POST">
<input type="text" name="name">

<!-- Try removing this or changing its value
     and see what happens -->
<input type="hidden" name="csrf_token" value="{{ .token }}">
<input type="submit" value="Send">
</form>
</body>
</html>
`
var templ = template.Must(template.New("t1").Parse(templateString))

func myFunc(w http.ResponseWriter, r *http.Request) {
	context := make(map[string]string)
	context["token"] = nosurf.Token(r)
	if r.Method == "POST" {
		context["name"] = r.FormValue("name")
	}
	
templ.Execute(w, context)
}

func main() {
	myHandler := http.HandlerFunc(myFunc)
	fmt.Println("Listening on http://127.0.0.1:8000/")
	http.ListenAndServe(":8000", nosurf.New(myHandler))
}
```

--------------------------------

### Get CSRF Token from Request

Source: https://pkg.go.dev/github.com/justinas/nosurf

Retrieves the CSRF token from an HTTP request. The token is unavailable after the request is served.

```go
func Token(req *http.Request) string
```

--------------------------------

### Get CSRF Check Failure Reason

Source: https://pkg.go.dev/github.com/justinas/nosurf

Retrieves the reason for a CSRF check failure from an HTTP request.

```go
func Reason(req *http.Request) error
```

--------------------------------

### Serve HTTP Request with CSRF Protection

Source: https://pkg.go.dev/github.com/justinas/nosurf

Handles incoming HTTP requests, performing CSRF checks before invoking the next handler.

```go
func (h *CSRFHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)
```

--------------------------------

### Create New CSRF Handler (Pure)

Source: https://pkg.go.dev/github.com/justinas/nosurf

Creates a new CSRF handler with an interface return type, similar to New().

```go
func NewPure(handler http.Handler) http.Handler
```

--------------------------------

### CSRFHandler Creation

Source: https://pkg.go.dev/github.com/justinas/nosurf

Provides methods for creating and configuring the CSRFHandler.

```APIDOC
## CSRFHandler

### Description

The CSRFHandler is the main type for providing CSRF protection.

### Functions

#### func New(handler http.Handler) *CSRFHandler

Constructs a new CSRFHandler that calls the specified handler if the CSRF check succeeds.

#### func NewPure(handler http.Handler) http.Handler

The same as New(), but has an interface return type.
```

--------------------------------

### Create New CSRF Handler

Source: https://pkg.go.dev/github.com/justinas/nosurf

Constructs a new CSRFHandler that will pass requests to the specified handler upon successful CSRF checks.

```go
func New(handler http.Handler) *CSRFHandler
```

--------------------------------

### CSRF Constants and Variables

Source: https://pkg.go.dev/github.com/justinas/nosurf

Defines constants and variables used within the NoSurf package.

```APIDOC
## CSRF Constants and Variables

### Constants

```go
const (
	// the name of CSRF cookie
	CookieName = "csrf_token"
	// the name of the form field
	FormFieldName = "csrf_token"
	// the name of CSRF header
	HeaderName = "X-CSRF-Token"
	// the HTTP status code for the default failure handler
	FailureCode = 400

	// Max-Age in seconds for the default base cookie. 365 days.
	MaxAge = 365 * 24 * 60 * 60
)
```

### Variables

```go
var (
	ErrNoReferer  = errors.New("A secure request contained no Referer or its value was malformed")
	ErrBadReferer = errors.New("A secure request's Referer comes from a different origin" +
		" from the request's URL")
	ErrBadOrigin = errors.New("Request was made with a disallowed origin specified in the Origin header")
	ErrBadToken  = errors.New("The CSRF token in the cookie doesn't match the one"
		" received in a form/header.")
)
```

Reasons for CSRF check failures.
```

--------------------------------

### Create Origin Validation Function

Source: https://pkg.go.dev/github.com/justinas/nosurf

Generates a function to validate request origins against a static list. Use this with SetIsAllowedOriginFunc.

```go
func StaticOrigins(origins ...string) (func(r *url.URL) bool, error)
```

--------------------------------

### CSRF Handler Configuration

Source: https://pkg.go.dev/github.com/justinas/nosurf

Methods for configuring exemptions, cookie settings, and failure handlers for CSRF protection.

```APIDOC
## CSRFHandler Configuration

### func (h *CSRFHandler) ExemptFunc(fn func(r *http.Request) bool)

### func (h *CSRFHandler) ExemptGlob(pattern string)

Exempts URLs that match the specified glob pattern (as used by filepath.Match()) from CSRF checks. Note that ExemptGlob() is unable to detect syntax errors, because it doesn't have a path to check it against and filepath.Match() doesn't report an error if the path is empty. If we find a way to check the syntax, ExemptGlob MIGHT PANIC on a syntax error in the future. ALWAYS check your globs for syntax errors.

### func (h *CSRFHandler) ExemptGlob(pattern string)

### func (h *CSRFHandler) ExemptGlob(pattern string)

### func (h *CSRFHandler) ExemptGlob(pattern string)

### func (h *CSRFHandler) ExemptGlob(pattern string)

### func (h *CSRFHandler) ExemptGlob(pattern string)

### func (h *CSRFHandler) ExemptGlob(pattern string)

### func (h *CSRFHandler) ExemptGlob(pattern string)

### func (h *CSRFHandler) ExemptGlob(pattern string)

### func (h *CSRFHandler) IsExempt(r *http.Request) bool

### func (h *CSRFHandler) RegenerateToken(w http.ResponseWriter, r *http.Request) string

### func (h *CSRFHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)

### func (h *CSRFHandler) SetBaseCookie(cookie http.Cookie)

### func (h *CSRFHandler) SetFailureHandler(handler http.Handler)

### func (h *CSRFHandler) SetIsAllowedOriginFunc(f func(*url.URL) bool)

### func (h *CSRFHandler) SetIsTLSFunc(f func(*http.Request) bool)
```

--------------------------------

### CSRFHandler Configuration Methods

Source: https://pkg.go.dev/github.com/justinas/nosurf

Methods for exempting specific paths or patterns from CSRF checks and configuring handler behavior.

```APIDOC
## ExemptPath

### Description
Exempts an exact path from CSRF checks. Note that Go's paths include a leading slash.

### Method
func (*CSRFHandler) ExemptPath(path string)

## ExemptPaths

### Description
A variadic argument version of ExemptPath().

### Method
func (*CSRFHandler) ExemptPaths(paths ...string)

## ExemptGlobs

### Description
A variadic argument version of ExemptGlob().

### Method
func (*CSRFHandler) ExemptGlobs(patterns ...string)

## ExemptRegexp

### Description
Accepts a regular expression string or a compiled *regexp.Regexp and exempts URLs that match it from CSRF checks.

### Method
func (*CSRFHandler) ExemptRegexp(re interface{})

## ExemptRegexps

### Description
A variadic argument version of ExemptRegexp().

### Method
func (*CSRFHandler) ExemptRegexps(res ...interface{})
```

--------------------------------

### Define CSRF Constants

Source: https://pkg.go.dev/github.com/justinas/nosurf

Defines constants for cookie name, form field name, header name, failure status code, and default cookie max age.

```go
const (
	// the name of CSRF cookie
	CookieName = "csrf_token"
	// the name of the form field
	FormFieldName = "csrf_token"
	// the name of CSRF header
	HeaderName = "X-CSRF-Token"
	// the HTTP status code for the default failure handler
	FailureCode = 400

	// Max-Age in seconds for the default base cookie. 365 days.
	MaxAge = 365 * 24 * 60 * 60
)
```

--------------------------------

### Verify CSRF Token

Source: https://pkg.go.dev/github.com/justinas/nosurf

Compares a sent CSRF token against the expected token, supporting masked tokens.

```go
func VerifyToken(realToken, sentToken string) bool
```

--------------------------------

### Set TLS Validation Function

Source: https://pkg.go.dev/github.com/justinas/nosurf

Sets a custom function to determine if the request is considered secure (e.g., using TLS).

```go
func (h *CSRFHandler) SetIsTLSFunc(f func(*http.Request) bool)
```

--------------------------------

### CSRF Token Management

Source: https://pkg.go.dev/github.com/justinas/nosurf

APIs for retrieving and verifying CSRF tokens.

```APIDOC
## CSRF Token Functions

### func Token(req *http.Request) string

Token takes an HTTP request and returns the CSRF token for that request or an empty string if the token does not exist. Note that the token won't be available after CSRFHandler finishes (that is, in another handler that wraps it, or after the request has been served).

### func VerifyToken(realToken, sentToken string) bool

VerifyToken verifies the sent token equals the real one and returns a bool value indicating if tokens are equal. Supports masked tokens. realToken comes from Token(r) and sentToken is token sent unusual way.
```

--------------------------------

### Regenerate CSRF Token

Source: https://pkg.go.dev/github.com/justinas/nosurf

Generates and sets a new CSRF token for the response.

```go
func (h *CSRFHandler) RegenerateToken(w http.ResponseWriter, r *http.Request) string
```

--------------------------------

### CSRFHandler Operational Methods

Source: https://pkg.go.dev/github.com/justinas/nosurf

Methods for managing tokens, checking exemptions, and setting custom security policies.

```APIDOC
## IsExempt

### Description
Checks if the given request is exempt from CSRF checks. It checks the ExemptFunc first, then the exact paths, then the globs and finally the regexps.

### Method
func (*CSRFHandler) IsExempt(r *http.Request) bool

## RegenerateToken

### Description
Generates a new token, sets it on the given request and returns it.

### Method
func (*CSRFHandler) RegenerateToken(w http.ResponseWriter, r *http.Request) string

## SetBaseCookie

### Description
Sets the base cookie to use when building a CSRF token cookie (e.g., Domain, Path, HttpOnly, Secure).

### Method
func (*CSRFHandler) SetBaseCookie(cookie http.Cookie)

## SetFailureHandler

### Description
Sets the handler to call in case the CSRF check fails.

### Method
func (*CSRFHandler) SetFailureHandler(handler http.Handler)

## SetIsAllowedOriginFunc

### Description
Defines a function that checks whether the request comes from an allowed origin.

### Method
func (*CSRFHandler) SetIsAllowedOriginFunc(f func(*url.URL) bool)

## SetIsTLSFunc

### Description
Sets a delegate function which determines, on a per-request basis, whether the request is made over a secure connection.

### Method
func (*CSRFHandler) SetIsTLSFunc(f func(*http.Request) bool)
```

--------------------------------

### Set Base CSRF Cookie

Source: https://pkg.go.dev/github.com/justinas/nosurf

Configures the base http.Cookie used for CSRF token storage.

```go
func (h *CSRFHandler) SetBaseCookie(cookie http.Cookie)
```

--------------------------------

### Define CSRF Error Variables

Source: https://pkg.go.dev/github.com/justinas/nosurf

Defines variables for common CSRF check failure errors.

```go
var (
	ErrNoReferer  = errors.New("A secure request contained no Referer or its value was malformed")
	ErrBadReferer = errors.New("A secure request's Referer comes from a different origin" +
		" from the request's URL")
	ErrBadOrigin = errors.New("Request was made with a disallowed origin specified in the Origin header")
	ErrBadToken  = errors.New("The CSRF token in the cookie doesn't match the one"
		" received in a form/header.")
)
```

--------------------------------

### Exempting Endpoints from CSRF Checks

Source: https://pkg.go.dev/github.com/justinas/nosurf

Use exemption methods like ExemptFunc, ExemptGlob, ExemptPath, ExemptRegexp to exclude specific endpoints from CSRF verification. This is useful when tokens are handled through non-standard means.

```go
	func (h *CSRFHandler) ExemptFunc(fn func(r *http.Request) bool)
	func (h *CSRFHandler) ExemptGlob(pattern string)
	func (h *CSRFHandler) ExemptGlobs(patterns ...string)
	func (h *CSRFHandler) ExemptPath(path string)
	func (h *CSRFHandler) ExemptPaths(paths ...string)
	func (h *CSRFHandler) ExemptRegexp(re interface{})
	func (h *CSRFHandler) ExemptRegexps(res ...interface{})
```

--------------------------------

### Set CSRF Failure Handler

Source: https://pkg.go.dev/github.com/justinas/nosurf

Specifies a custom http.Handler to be invoked when a CSRF check fails.

```go
func (h *CSRFHandler) SetFailureHandler(handler http.Handler)
```

--------------------------------

### Manual CSRF Token Verification

Source: https://pkg.go.dev/github.com/justinas/nosurf

Manually verify CSRF tokens when they are sent through non-standard methods like JSON bodies. Use nosurf.VerifyToken with the token from the request and the token sent in the body.

```go
func HandleJson(w http.ResponseWriter, r *http.Request) {
	d := struct{
		X,Y int
		Tkn string
	}{}
	json.Unmarshal(ioutil.ReadAll(r.Body), &d)
	if !nosurf.VerifyToken(nosurf.Token(r), d.Tkn) {
		http.Errorf(w, "CSRF token incorrect", http.StatusBadRequest)
		return
	}
	// do smth cool
}
```

--------------------------------

### CSRF Handler Type

Source: https://pkg.go.dev/github.com/justinas/nosurf

Represents a CSRF handler that performs checks before passing requests to the next handler.

```go
type CSRFHandler struct {
	// contains filtered or unexported fields
}
```

--------------------------------

### Exempt Request from CSRF Check (Glob Pattern)

Source: https://pkg.go.dev/github.com/justinas/nosurf

Exempts URLs matching a glob pattern from CSRF checks. Be cautious of potential syntax errors.

```go
func (h *CSRFHandler) ExemptGlob(pattern string)
```

--------------------------------

### Set Allowed Origin Validation Function

Source: https://pkg.go.dev/github.com/justinas/nosurf

Sets a custom function to determine if an origin is allowed for CSRF checks.

```go
func (h *CSRFHandler) SetIsAllowedOriginFunc(f func(*url.URL) bool)
```

--------------------------------

### Exempt Requests from CSRF Check (Paths)

Source: https://pkg.go.dev/github.com/justinas/nosurf

Exempts multiple specific URL paths from CSRF checks.

```go
func (h *CSRFHandler) ExemptPaths(paths ...string)
```

--------------------------------

### Exempt Requests from CSRF Check (Glob Patterns)

Source: https://pkg.go.dev/github.com/justinas/nosurf

Exempts multiple URLs matching glob patterns from CSRF checks.

```go
func (h *CSRFHandler) ExemptGlobs(patterns ...string)
```

--------------------------------

### Exempt Request from CSRF Check (Path)

Source: https://pkg.go.dev/github.com/justinas/nosurf

Exempts a specific URL path from CSRF checks.

```go
func (h *CSRFHandler) ExemptPath(path string)
```

--------------------------------

### Exempt Requests from CSRF Check (Regexps)

Source: https://pkg.go.dev/github.com/justinas/nosurf

Exempts requests matching multiple regular expressions from CSRF checks.

```go
func (h *CSRFHandler) ExemptRegexps(res ...interface{})
```

--------------------------------

### Exempt Request from CSRF Check (Regexp)

Source: https://pkg.go.dev/github.com/justinas/nosurf

Exempts requests matching a regular expression from CSRF checks.

```go
func (h *CSRFHandler) ExemptRegexp(re interface{})
```

--------------------------------

### Exempt Request from CSRF Check (Function)

Source: https://pkg.go.dev/github.com/justinas/nosurf

Allows exempting requests from CSRF checks based on a provided function.

```go
func (h *CSRFHandler) ExemptFunc(fn func(r *http.Request) bool)
```

--------------------------------

### CSRF Reason and Origin Validation

Source: https://pkg.go.dev/github.com/justinas/nosurf

Functions to determine the reason for CSRF failure and to validate request origins.

```APIDOC
## CSRF Reason and Origin Functions

### func Reason(req *http.Request) error

Reason takes an HTTP request and returns the reason of failure of the CSRF check for that request. Note that the same availability restrictions apply for Reason() as for Token().

### func StaticOrigins(origins ...string) (func(r *url.URL) bool, error)

StaticOrigins returns a delegate, suitable for passing to CSRFHandler.SetIsAllowedOriginFunc, that validates the request origin against a static list of allowed origins. This function expects each element to be of form `scheme://host`, e.g.: `https://example.com`, `http://example.org`. If any element of the slice is an invalid URL, this function will return an error. If an element includes additional URL parts (e.g. a path), these parts will be ignored, as origin checks only take the scheme and host into account.

Example:
```go
h := nosurf.New()
origins, err := nosurf.StaticOrigins("https://api.example.com", "http://insecure.example.com")
if err != nil {
	panic(err)
}
h.SetIsAllowedOriginFunc(origins)
```
```

--------------------------------

### Check if Request is Exempt from CSRF

Source: https://pkg.go.dev/github.com/justinas/nosurf

Determines if a given HTTP request is exempt from CSRF checks.

```go
func (h *CSRFHandler) IsExempt(r *http.Request) bool
```
Tokens:
Raw