Struct actix_csrf::CsrfMiddleware

source · [−]

pub struct CsrfMiddleware<Rng> { /* private fields */ }

Expand description

CSRF middleware to manage CSRF cookies and tokens.

Implementations

source

impl<Rng: TokenRng + SeedableRng> CsrfMiddleware<Rng>

source

pub fn new() -> Self

Creates a CSRF middleware with secure defaults. Namely:

The CSRF cookie will be prefixed with __Host-. This also implies the following:
- Secure is set.
- Domain is not set.
- Path is set to /.
SameSite is set to Strict.
HttpOnly is set.

This represents the strictest possible configuration. Requests must be always sent over HTTPS. Users must explicitly relax these restrictions.

source

impl<Rng: TokenRng> CsrfMiddleware<Rng>

source

pub fn with_rng(rng: Rng) -> Self

Creates a CSRF middleware with secure defaults and the provided Rng. Namely:

The CSRF cookie will be prefixed with __Host-. This also implies the following:
- Secure is set.
- Domain is not set.
- Path is set to /.
SameSite is set to Strict.
HttpOnly is set.

This represents the strictest possible configuration. Requests must be always sent over HTTPS. Users must explicitly relax these restrictions.

source

impl<Rng> CsrfMiddleware<Rng>

source

pub const fn enabled(self, enabled: bool) -> Self

Control whether we check for the token on requests.

source

pub fn set_cookie<T: Into<String>>(self, method: Method, uri: T) -> Self

Set a method and path to set a CSRF cookie. This should be all locations that whose response should set a cookie (via a Set-Cookie header) or those that need the CSRF token value in the response, such as for forms.

source

pub fn cookie_name<T: Into<String>>(self, name: T) -> Self

Sets the cookie name. Consider using host_prefixed_cookie_name or secure_prefixed_cookie_name to prefix the cookie name with __Host- or __Secure- on your behalf, or prefixing it manually.

source

pub fn host_prefixed_cookie_name<T: AsRef<str>>(self, name: T) -> Self

Sets the cookie name, with __Host- automatically prefixed.

Examples

This functionally is equivalent to prefixing the cookie name with __Host-:

use actix_csrf::CsrfMiddleware;
use rand::rngs::StdRng;

let host_prefixed = CsrfMiddleware::<StdRng>::new()
    .host_prefixed_cookie_name("my_special_cookie");
let manually_prefixed = CsrfMiddleware::<StdRng>::new()
    .cookie_name("__Host-my_special_cookie");
assert_eq!(host_prefixed.cookie_config(), manually_prefixed.cookie_config());

source

pub fn secure_prefixed_cookie_name<T: AsRef<str>>(self, name: T) -> Self

Sets the cookie name. Consider using host_prefixed_cookie_name or manually prefixing it with __Host- for increased defense-in-depth measures. This is equivalent to calling cookie_name(format!("__Secure-{}", name)).

Examples

This functionally is equivalent to prefixing the cookie name with __Secure-:

use actix_csrf::CsrfMiddleware;
use rand::rngs::StdRng;

let host_prefixed = CsrfMiddleware::<StdRng>::new()
    .secure_prefixed_cookie_name("my_special_cookie");
let manually_prefixed = CsrfMiddleware::<StdRng>::new()
    .cookie_name("__Secure-my_special_cookie");
assert_eq!(host_prefixed.cookie_config(), manually_prefixed.cookie_config());

source

pub const fn same_site(self, same_site: Option<SameSite>) -> Self

Sets the SameSite attribute on the cookie.

source

pub const fn http_only(self, enabled: bool) -> Self

Sets the HttpOnly attribute on the cookie.

source

pub const fn secure(self, enabled: bool) -> Self

Sets the Secure attribute on the cookie.

source

pub fn domain<S: Into<String>>(self, domain: impl Into<Option<S>>) -> Self

Sets the domain of the cookie.

This is incompatible with __Host- prefixed cookies. If the cookie is a __Host- prefixed cookie, this function will downgrade the cookie to a use the __Secure- prefix instead. This weakens a defense-in-depth measure and is not recommended unless there is an unavoidable need and the security implications have been fully considered.

source