Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
Cutelyst4Qt6CSRFProtection(5)  File Formats Manual Cutelyst4Qt6CSRFProtection(5)

NAME
     Cutelyst4Qt6CSRFProtection - Configuration of the CSRFProtection Plugin for
     the Cutelyst Web Framework

DESCRIPTION
     The  CSRFProtection plugin implements a synchronizer token pattern (STP) to
     protect input forms against Cross Site Request Forgery (CSRF/XSRF) attacks.
     This type of attack occurs when a malicious website contains a link, a form
     button or some JavaScript that is intended to perform some action	on  your
     website, using the credentials of a logged-in user who visits the malicious
     site in their browser.

CONFIGURATION
     There  are  some options you can set in your application configuration file
     in the Cutelyst_CSRFProtection_Plugin section.

     cookie_expiration (integer or string value, default: 1 year)
	 The expiration time of the cookie. Can be given as time span where  the
	 following time units are understood:

	 *   usec, us

	 *   msec, ms

	 *   seconds, second, sec, s

	 *   minutes, minute, min, m

	 *   hours, hour, hr, h

	 *   days, day, d

	 *   weeks, week, w

	 *   months, month, M (defined as 30.44 days)

	 *   years, year, y (defined as 365.25 days)

	 If  no  time unit is specified, generally seconds are assumed. Examples
	 for valid time span specifications:

	     2 h
	     2hours
	     48hr
	     1y 12month
	     55s500ms
	     300ms20s 5day

	 The reason for setting a long-lived expiration time is to  avoid  prob-
	 lems  in the case of a user closing a browser or bookmarking a page and
	 then loading that page from a browser cache. Without  persistent  cook-
	 ies, the form submission would fail in this case.

	 Some  browsers (specifically Internet Explorer) can disallow the use of
	 persistent cookies or can have the indexes to the cookie jar  corrupted
	 on disk, thereby causing CSRF protection checks to (sometimes intermit-
	 tently)  fail. Change this setting to 0 to use session-based CSRF cook-
	 ies, which keep the cookies in-memory instead of on persistent storage.

     cookie_domain (string value, default: empty)
	 The domain to be used when setting the CSRF cookie. This can be  useful
	 for  easily  allowing	cross-subdomain requests to be excluded from the
	 normal cross site request forgery protection. It should  be  set  to  a
	 string  such  as  ".example.com" to allow a POST request from a form on
	 one subdomain to be accepted by a view served from another subdomain.

	 Please note that the presence of this setting does not imply  that  the
	 CSRF  protection  is  safe  from  cross-subdomain  attacks by default -
	 please see the NOTES section.

     cookie_secure (boolean value, default: false)
	 Whether to use a secure cookie for the CSRF cookie. If this is  set  to
	 true, the cookie will be marked as secure, which means browsers may en-
	 sure that the cookie is only sent with an HTTPS connection.

     cookie_same_site (string value, default: strict)
	 Defines the SameSite attribute of the CSRF cookie. Read the MDN article
	 to  learn more about SameSite cookies. This configuration key is avail-
	 able since Cutelyst 3.8.0. Acceptable values are:

	 *   default - SameSite is not set. Can be interpreted as None or Lax by
	     the browser.

	 *   none - Cookies can be sent in all contexts. This  used  to  be  de-
	     fault,  but  recent browsers made Lax default, and will now require
	     the cookie to be both secure and to set SameSite=None.

	 *   lax - Cookies are sent on first party  requests  and  GET	requests
	     initiated	by  third  party  website. This is the default in modern
	     browsers (since mid 2020).

	 *   strict - Cookies will only be sent in a first-party context.

     trusted_origins (string list, default: empty)
	 A comma separated list of hosts which are trusted  origins  for  unsafe
	 requests  (e.g. POST). For a secure unsafe request, the CSRF protection
	 requires that the request have a Referer header that matches the origin
	 present in the Host header. This prevents, for example, a POST  request
	 from subdomain.example.com from succeeding against api.example.com.  If
	 you  need cross-origin unsafe requests over HTTPS, continuing the exam-
	 ple, add "subdomain.example.com" to this list. The  setting  also  sup-
	 ports	subdomains, so you could add ".example.com", for example, to al-
	 low access from all subdomains of example.com.

     log_failed_ip (boolean value, default: false)
	 If this is set to true, the log output for failed checks  will  contain
	 the IP address of the remote client.

EXAMPLES
     [Cutelyst_CSRFProtection_Plugin]
     cookie_secure=true

NOTES
     Subdomains  within a site will be able to set cookies on the client for the
     whole domain. By setting the cookie and using a corresponding token, subdo-
     mains will be able to circumvent the CSRF protection. The only way to avoid
     this is to ensure that subdomains are controlled by trusted users (or,  are
     at  least	unable	to  set cookies). Note that even without CSRF, there are
     other vulnerabilities, such as session fixation, that  make  giving  subdo-
     mains  to	untrusted  parties  a bad idea, and these vulnerabilities cannot
     easily be fixed with current browsers.

LOGGING CATEGORY
     cutelyst.plugin.csrfprotection

Cutelyst4Qt6CSRFProtection 4.7.0   2023-11-08	   Cutelyst4Qt6CSRFProtection(5)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=Cutelyst4Qt6CSRFProtection&sektion=5&manpath=FreeBSD+Ports+15.1.quarterly>

home | help