Documentation
¶
Index ¶
- Variables
- func Protect(authKey []byte, opts ...Option) func(opm.Handler) opm.Handler
- func TemplateField(c opm.Context) template.HTML
- func Token(c opm.Context) string
- type Option
- func CookieName(name string) Option
- func Domain(domain string) Option
- func FieldName(name string) Option
- func HttpOnly(h bool) Option
- func MaxAge(age int) Option
- func Path(p string) Option
- func RequestHeader(header string) Option
- func SameSite(s SameSiteMode) Option
- func Secure(s bool) Option
- func TrustedOrigins(origins []string) Option
- type SameSiteMode
Constants ¶
This section is empty.
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. <input type="hidden" name="csrf.Token" value="{{.csrf}}"> - for use with the TemplateField function.
Functions ¶
func TemplateField ¶
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:
<input type="hidden" name="csrf.Token" value="{{.csrf}}">
// ... becomes:
<input type="hidden" name="csrf.Token" value="<token>">
Types ¶
type Option ¶
type Option func(*csrf)
Option describes a functional option for configuring the CSRF handler.
func CookieName ¶
CookieName changes the name of the CSRF cookie issued to clients.
Note that cookie names should not contain whitespace, commas, semicolons, backslashes or control characters as per RFC6265.
func Domain ¶
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 FieldName ¶
FieldName allows you to change the name attribute of the hidden <input> field inspected by this package. The default is 'gorilla.csrf.Token'.
func MaxAge ¶
MaxAge sets the maximum age (in seconds) of a CSRF token's underlying cookie. Defaults to 12 hours. Call csrf.MaxAge(0) to explicitly set session-only cookies.
func Path ¶
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 RequestHeader ¶
RequestHeader allows you to change the request header the CSRF middleware inspects. The default is X-CSRF-Token.
func SameSite ¶
func SameSite(s SameSiteMode) 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 Secure ¶
Secure sets the 'Secure' flag on the cookie. Defaults to true (recommended). Set this to 'false' in your development environment otherwise the cookie won't be sent over an insecure channel. Setting this via the presence of a 'DEV' environmental variable is a good way of making sure this won't make it to a production environment.
func TrustedOrigins ¶
TrustedOrigins configures a set of origins (Referers) that are considered as trusted. This will allow cross-domain CSRF use-cases - e.g. where the front-end is served from a different domain than the API server - to correctly pass a CSRF check.
You should only provide origins you own or have full control over.
type SameSiteMode ¶
type SameSiteMode int
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.
const ( // SameSiteDefaultMode sets the `SameSite` cookie attribute, which is // invalid in some older browsers due to changes in the SameSite spec. These // browsers will not send the cookie to the server. // csrf uses SameSiteLaxMode (SameSite=Lax) as the default as of v1.7.0+ SameSiteDefaultMode SameSiteMode = iota + 1 SameSiteLaxMode SameSiteStrictMode SameSiteNoneMode )
SameSite options
Source Files