Struct CsrfMiddleware

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

CSRF middleware to manage CSRF cookies and tokens.

Implementations

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

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.

impl<Rng: TokenRng> CsrfMiddleware<Rng>

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.

impl<Rng> CsrfMiddleware<Rng>

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

Control whether we check for the token on requests.

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.

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.

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());

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());

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

Sets the SameSite attribute on the cookie.

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

Sets the HttpOnly attribute on the cookie.

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

Sets the Secure attribute on the cookie.

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.

pub fn cookie_config(&self) -> CsrfCookieConfig

Produces an CSRF cookie config determined from the current middleware state. Note that this is not needed if you are using default cookie names.

Trait Implementations

impl<Rng: Clone> Clone for CsrfMiddleware<Rng>

fn clone(&self) -> CsrfMiddleware<Rng>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<Rng: Debug> Debug for CsrfMiddleware<Rng>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

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

fn default() -> Self

Returns the “default value” for a type.

impl<Rng: PartialEq> PartialEq for CsrfMiddleware<Rng>

fn eq(&self, other: &CsrfMiddleware<Rng>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<S, Rng> Transform<S, ServiceRequest> for CsrfMiddleware<Rng>

where S: Service<ServiceRequest, Response = ServiceResponse>, Rng: TokenRng + Clone,

type Response = ServiceResponse

Responses produced by the service.

type Error = <S as Service<ServiceRequest>>::Error

Errors produced by the service.

type InitError = ()

Errors produced while building a transform service.

type Transform = CsrfMiddlewareImpl<S, Rng>

The TransformService value created by this factory

type Future = Ready<Result<<CsrfMiddleware<Rng> as Transform<S, ServiceRequest>>::Transform, <CsrfMiddleware<Rng> as Transform<S, ServiceRequest>>::InitError>>

The future response value.

fn new_transform(&self, service: S) -> Self::Future

Creates and returns a new Transform component, asynchronously

impl<Rng: Eq> Eq for CsrfMiddleware<Rng>

impl<Rng> StructuralPartialEq for CsrfMiddleware<Rng>