Struct axum_csrf::CsrfConfig

pub struct CsrfConfig {
    pub(crate) lifespan: Duration,
    pub(crate) cookie_name: String,
    pub(crate) cookie_len: usize,
    pub(crate) cookie_domain: Option<Cow<'static, str>>,
    pub(crate) cookie_http_only: bool,
    pub(crate) cookie_path: Cow<'static, str>,
    pub(crate) cookie_same_site: SameSite,
    pub(crate) cookie_secure: bool,
    pub(crate) key: Option<Key>,
    pub(crate) salt: Cow<'static, str>,
    pub(crate) prefix_with_host: bool,
}

This is the CSRF Config it is used to manage how we set the Restricted Cookie.

Fields

lifespan: Duration

CSRF Cookie lifespan

cookie_name: String

CSRF cookie name

cookie_len: usize

CSRF Token character length

cookie_domain: Option<Cow<'static, str>>

Session cookie domain

cookie_http_only: bool

Session cookie http only flag

cookie_path: Cow<'static, str>

Session cookie http only flag

cookie_same_site: SameSite

Resticts how Cookies are sent cross-site. Default is SameSite::None Only works if domain is also set.

cookie_secure: bool

Session cookie secure flag

key: Option<Key>

Encyption Key used to encypt cookies for confidentiality, integrity, and authenticity.

salt: Cow<'static, str>

Hashing Salt.

prefix_with_host: bool

This is used to append __Host- to the front of all Cookie names to prevent sub domain usage. It is disabled by default.

Implementations

impl CsrfConfig

pub fn new() -> Self

Creates Default configuration of CsrfConfig. This is equivalent to the CsrfConfig::default().

pub fn with_cookie_domain( self, name: impl Into<Option<Cow<'static, str>>> ) -> Self

Set’s the csrf’s cookie’s domain name.

Examples

use axum_csrf::CsrfConfig;

let config = CsrfConfig::default().with_cookie_domain(Some("www.helpme.com".to_string()));

pub fn with_lifetime(self, time: Duration) -> Self

Set’s the csrf’s lifetime (expiration time).

Examples

use axum_csrf::CsrfConfig;
use chrono::Duration;

let config = CsrfConfig::default().with_lifetime(Duration::days(32));

pub fn with_cookie_name(self, name: &str) -> Self

Set’s the csrf’s cookie’s name.

Examples

use axum_csrf::CsrfConfig;

let config = CsrfConfig::default().with_cookie_name("my_cookie");

pub fn with_cookie_path(self, path: impl Into<Cow<'static, str>>) -> Self

Set’s the csrf’s cookie’s path.

This is used to deturmine when the cookie takes effect within the website path. Leave as default (“/”) for cookie to be used site wide.

Examples

use axum_csrf::CsrfConfig;

let config = CsrfConfig::default().with_cookie_path("/");

pub fn with_cookie_same_site(self, same_site: SameSite) -> Self

Set’s the csrf’s cookie’s Same Site Setting for Cross-Site restrictions.

Only works if Domain is also set to restrict it to that domain only.

Examples

use axum_csrf::CsrfConfig;
use cookie::SameSite;

let config = CsrfConfig::default().with_cookie_same_site(SameSite::Strict);

pub fn with_http_only(self, is_set: bool) -> Self

Set’s the csrf’s cookie’s to http only.

Examples

use axum_csrf::CsrfConfig;

let config = CsrfConfig::default().with_http_only(false);

pub fn with_secure(self, is_set: bool) -> Self

Set’s the csrf’s secure flag for if it gets sent over https.

Examples

use axum_csrf::CsrfConfig;

let config = CsrfConfig::default().with_secure(true);

pub fn with_cookie_len(self, length: usize) -> Self

Set’s the csrf’s token length.

Examples

use axum_csrf::CsrfConfig;

let config = CsrfConfig::default().with_cookie_len(16);

pub fn with_key(self, key: Option<Key>) -> Self

Set’s the csrf’s cookie encyption key enabling private cookies.

When Set it will enforce Private cookies across all Sessions. If you use Key::generate() it will make a new key each server reboot. To prevent this make and save a key to a config file for long term usage. For Extra Security Regenerate the key every so many months to a year.

Examples

use axum_csrf::{Key, CsrfConfig};

let config = CsrfConfig::default().with_key(Key::generate());

pub fn with_salt(self, salt: impl Into<Cow<'static, str>>) -> Self

Set’s the csrf’s cookie’s salt.

This is used to hash the CSRF key for the html insertion.

Examples

use axum_csrf::CsrfConfig;

let config = CsrfConfig::default().with_salt("somesalthere");

pub fn with_prefix_with_host(self, enable: bool) -> Self

Set’s the CSRF’s prefix_with_host to either true: __Host- gets prefixed to the cookie names false: __Host- does not get prepended.

__Host- prefix: Cookies with names starting with __Host- must be set with the secure flag, must be from a secure page (HTTPS), must not have a domain specified (and therefore, are not sent to subdomains), and the path must be /.

Examples

use axum_csrf::CsrfConfig;

let config = CsrfConfig::default().with_prefix_with_host(true);

Trait Implementations

impl Clone for CsrfConfig

fn clone(&self) -> CsrfConfig

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for CsrfConfig

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

Formats the value using the given formatter.

impl Default for CsrfConfig

fn default() -> Self

Returns the “default value” for a type.