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 problems in the case of a user closing a browser or bookmarking a page and then loading that page from a browser cache. Without persistent cookies, 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 intermittently) fail. Change this setting to 0 to use session-based CSRF cookies, 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 ensure 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 available 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 default, 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 example, add "subdomain.example.com" to this list. The setting also supports subdomains, so you could add ".example.com", for example, to allow 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, subdomains 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 subdomains to untrusted parties a bad idea, and these vulnerabilities cannot easily be fixed with current browsers.

LOGGING CATEGORY

cutelyst.plugin.csrfprotection