Documentation
¶
Index ¶
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. {{ .csrfField }} - for use with the TemplateField function.
Functions ¶
func FailureReason ¶
func FailureReason(ctx iris.Context) error
FailureReason makes CSRF validation errors available in the request context. This is useful when you want to log the cause of the error or report it to client.
func Protect ¶
Protect is HTTP middleware that provides Cross-Site Request Forgery protection.
It securely generates a masked (unique-per-request) token that can be embedded in the HTTP response (e.g. form field or HTTP header). The original (unmasked) token is stored in the session, which is inaccessible by an attacker (provided you are using HTTPS). Subsequent requests are expected to include this token, which is compared against the session token. Requests that do not provide a matching token are served with a HTTP 403 'Forbidden' error response.
Example: https://github.com/jonsen/middleware/tree/master/csrf/_example
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:
{{ .csrfField }}
// ... becomes:
<input type="hidden" name="csrf.Token" value="<token>">
func Token ¶
func Token(ctx iris.Context) string
Token returns a masked CSRF token ready for passing into HTML template or a JSON response body. An empty token will be returned if the middleware has not been applied (which will fail subsequent validation).
func UnsafeSkipCheck ¶
func UnsafeSkipCheck(ctx iris.Context)
UnsafeSkipCheck will skip the CSRF check for any requests. This must be called before the CSRF middleware.
Note: You should not set this without otherwise securing the request from CSRF attacks. The primary use-case for this function is to turn off CSRF checks for non-browser clients using authorization tokens against your API.
Types ¶
type Csrf ¶
type Csrf struct {
// contains filtered or unexported fields
}
Csrf the middleware container.
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 ErrorHandler ¶
func ErrorHandler(h iris.Handler) Option
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 default a HTTP 403 status and a plain text CSRF failure reason are served.
Note that a custom error handler can also access the csrf.FailureReason(r) function to retrieve the CSRF validation reason from the request context.
func FieldName ¶
FieldName allows you to change the name attribute of the hidden <input> field inspected by this package. The default is 'csrf.Token'.
func MaxAge ¶
MaxAge sets the maximum age (in seconds) of a CSRF token's underlying cookie. Defaults to 12 hours.
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 Secure ¶
Secure sets the 'Secure' flag on the cookie. Defaults to true (is recommended but requires https). 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.
Source Files
Directories