Cutelyst  2.13.0
Public Member Functions | Static Public Member Functions | Protected Member Functions | List of all members
Cutelyst::CSRFProtection Class Reference

Protect input forms against Cross Site Request Forgery (CSRF/XSRF) attacks. More...

#include <Cutelyst/Plugins/CSRFProtection/CSRFProtection>

Inheritance diagram for Cutelyst::CSRFProtection:
Inheritance graph

Public Member Functions

 CSRFProtection (Application *parent)
virtual ~CSRFProtection () override
void setCookieHttpOnly (bool httpOnly)
void setCookieName (const QString &cookieName)
void setDefaultDetachTo (const QString &actionNameOrPath)
void setErrorMsgStashKey (const QString &keyName)
void setFormFieldName (const QString &fieldName)
void setGenericErrorContentTyp (const QString &type)
void setGenericErrorMessage (const QString &message)
void setHeaderName (const QString &headerName)
void setIgnoredNamespaces (const QStringList &namespaces)
void setUseSessions (bool useSessions)
- Public Member Functions inherited from Cutelyst::Plugin
 Plugin (Application *parent)

Static Public Member Functions

static bool checkPassed (Context *c)
static QByteArray getToken (Context *c)
static QString getTokenFormField (Context *c)

Protected Member Functions

virtual bool setup (Application *app) override

Detailed 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.

The first defense against CSRF attacks is to ensure that GET requests (and other safe methods, as defined by RFC 7231) are side effect free. Requests via unsafe methods, such as POST, PUT, and DELETE, can then be protected by this plugin.

This plugin has been inspired by the CSRF protection of the Django web framework.


For general usage and to protect any unsafe action, simply add the plugin to your application.

#include <Cutelyst/Plugins/CSRFProtection/CSRFProtection>
bool MyCutelystApp::init()
// other initialization stuff
auto csrfProtect = new CSRFProtection(this);
// optionally you can ignore complete namespaces from the protection
// more initialization stuff

To ignore an action from CSRF protection, add :CSRFIgnore to the attributes.

C_ATTR(index, :Path :AutoArgs :CSRFIgnore)
void index(Context *c);

If you have optionally ignored complete namespaces from the CSRF protection, you can require the protection for single namespace members by adding :CSRFRequire to the attributes.

class Foo : public Cutelyst::Controller
C_ATTR(index, :Path :AutoArgs)
void index(Context *c);
C_ATTR(edit, :Path :CSRFRequire)
void edit(Context *c);

In your Grantlee template you should then use the {% c_csrf_token %} tag in your forms to add a hidden input field that contains the CSRF protection token.

<form method="post">
{% c_csrf_token %}
<input type="text" name="username">
<input type="password" name="password">
<button type="submit">Login</button>

You can optionally get the token by using CSRFProtection::getToken() static function if you want to add it to the stash or want to use it elsewhere. For example, if you don't have a form on your site but want to use the token for an AJAX request and want to add it therefore into a meta tag or something like that.

Handling failed checks

If the CSRF protection check fails, the return code will be set to 403 - Forbidden and an error message will be set to the stash key defined by setErrorMsgStashKey(). You can set a default action the application should detach to if the check failed via setDefaultDetachTo(), optionally there is the attribute :CSRFDetachTo that can be used to define a detach to action per method. If the detach to action is not set or could not be found it will either set the response body to the content set by setGenericErrorMessage() of if that is absent it will generate a generic HTML content containing error information.

bool MyCutelystApp::init()
auto csrf = new CSRFProtection(this);
class Foo : public Cutelyst::Controller
C_ATTR(foo, :Local :CSRFDetachTo(csrfDenied))
void foo(Context *c);
C_ATTR(csrfDenied, :Local :Private :AutoArgs :ActionClass(RenderView))
vod csrfDenied(Context *c);

AJAX and CSRF protection

If you are using ajax to submit form requests or if you use AJAX without a HTML form, you have to provide the CSRF token too. If you are using the normal way by setting a cookie, you can read the CSRF token from that cookie. If you use the session to store the token, you have to include the token somewhere into the DOM tree from where you can read it. You can then add the extracted token to the POST data of every POST request or you can can set a custom X-CSRFToken header to the value of the CSRF token. The latter method is often easier, because many JavaScript frameworks provide hooks that allow headers to be set on every request.

How it works

On every request, a secret token is set that is stored in a cookie or in the user session and has to be send back to the application when performing actions on unsafe methods like POST. The token stored in the cookie or in the session is salted with another random value. The same secret with a different salt has then to be sent to the application either via a hidden form field or via a HTTP request header.

To get the form field you can use the {% c_csrf_token %} tag in your Grantlee templates. If you are not using Grantlee or if you do not use a form but AJAX, you can use CSRFProtection::getToken() to place the token somewhere in your DOM tree so that you can read it with JavaScript.


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.

Configuration file options

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


Integer value, default: 31449600

The age/expiration time of the cookie in seconds.

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.


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 "" 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 limitations section.


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.


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 from succeeding against If you need cross-origin unsafe requests over HTTPS, continuing the example, add "" to this list. The setting also supports subdomains, so you could add "", for example, to allow access from all subdomains of


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.

Build options

This plugin is not enabled by default. Use -DPLUGIN_CSRFPROTECTION:BOOL=ON for your cmake configuration. To link it to your application use Cutelyst::CSRFProtection.

Logging category
Cutelyst 1.12.0

Definition at line 227 of file csrfprotection.h.

Constructor & Destructor Documentation

◆ CSRFProtection()

CSRFProtection::CSRFProtection ( Application parent)

Constructs a new CSRFProtection object with the given parent.

Definition at line 66 of file csrfprotection.cpp.

◆ ~CSRFProtection()

CSRFProtection::~CSRFProtection ( )

Deconstructs the CSRFProtection object.

Definition at line 72 of file csrfprotection.cpp.

Member Function Documentation

◆ checkPassed()

bool CSRFProtection::checkPassed ( Context c)

Returns true if the CSRF protection check has successfully been passed. You can use this function in your contoller methods to handle CSRF protection results. For HTTP methods that are secure according to RFC 7231 (GET, HEAD, OPTIONS and TRACE) this will return always true. For all other methods it will return false if the CSRF protection check has failed.

Definition at line 220 of file csrfprotection.cpp.

References Cutelyst::Context::stash().

◆ getToken()

QByteArray CSRFProtection::getToken ( Context c)

Returns the current token.

Definition at line 186 of file csrfprotection.cpp.

References Cutelyst::Context::setStash(), and Cutelyst::Context::stash().

Referenced by getTokenFormField().

◆ getTokenFormField()

QString CSRFProtection::getTokenFormField ( Context c)

Returns HTML code for a hidden input field that contains the current token and has the name set by setFormFieldName(). This method is also used by the Grantlee tag {% c_csrf_token %}

Example output

<input type="hidden" name="csrfprotectiontoken" value="e2RiYmI1YWJjLTJiZTctNDczYS1iMDM2ipApLPunLnnbkAQrzJWMo9GoyiQpzkeT">

Definition at line 206 of file csrfprotection.cpp.

References getToken().

◆ setCookieHttpOnly()

void CSRFProtection::setCookieHttpOnly ( bool  httpOnly)

Whether to use HttpOnly flag on the CSRF cookie. If this is set to true, client-side JavaScript will not to be able to access the CSRF cookie. The default is false.

Designating the CSRF cookie as HttpOnly doesn’t offer any practical protection because CSRF is only to protect against cross-domain attacks. If an attacker can read the cookie via JavaScript, they’re already on the same domain as far as the browser knows, so they can do anything they like anyway. (XSS is a much bigger hole than CSRF.)

Although the setting offers little practical benefit, it’s sometimes required by security auditors.

If you enable this and need to send the value of the CSRF token with an AJAX request, your JavaScript must pull the value from a hidden CSRF token form input on the page instead of from the cookie.

Definition at line 156 of file csrfprotection.cpp.

◆ setCookieName()

void CSRFProtection::setCookieName ( const QString &  cookieName)

The name of the cookie to use for the CSRF authentication token. The default is "csrftoken". This can be whatever you want (as long as it’s different from the other cookie names in your application).

Definition at line 162 of file csrfprotection.cpp.

◆ setDefaultDetachTo()

void CSRFProtection::setDefaultDetachTo ( const QString &  actionNameOrPath)

Sets a default action the application will detach to if the check for token and cookie failed. The default value is empty, so that there will be no detaching and a generic error page will be generated.

Definition at line 118 of file csrfprotection.cpp.

◆ setErrorMsgStashKey()

void CSRFProtection::setErrorMsgStashKey ( const QString &  keyName)

Sets the name of the stash key that that will contains the error message if the CSRF protection check failed.

Definition at line 134 of file csrfprotection.cpp.

◆ setFormFieldName()

void CSRFProtection::setFormFieldName ( const QString &  fieldName)

Sets the name for the hidden form field that takes the CSRF token. This field name is used by CSRFProtection::getTokenFormField(). The default value is "csrfprotectiontoken".

Definition at line 124 of file csrfprotection.cpp.

◆ setGenericErrorContentTyp()

void CSRFProtection::setGenericErrorContentTyp ( const QString &  type)

Sets the content type for the error message set by setGenericErrorMessage(), defaults to text/plain; charset=utf-8.

Cutelyst 2.2.0

Definition at line 180 of file csrfprotection.cpp.

◆ setGenericErrorMessage()

void CSRFProtection::setGenericErrorMessage ( const QString &  message)

Sets a generic error message that will be set to the Response::body() if the check fails and if there is no action defined it should be detached to.

See also
Cuteyst 2.2.0

Definition at line 174 of file csrfprotection.cpp.

◆ setHeaderName()

void CSRFProtection::setHeaderName ( const QString &  headerName)

The name of the request header used for CSRF authentication. The header can contain the token if you don't have a input form on your protected site. The default value is "X-CSRFTOKEN".

Definition at line 168 of file csrfprotection.cpp.

◆ setIgnoredNamespaces()

void CSRFProtection::setIgnoredNamespaces ( const QStringList &  namespaces)

Sets a list of namespaces that should be completely ignored by the CSRF protection. If you have single methods in your namespaces that should still be protected, use the :CSRFRequire attribute on this methods.

Definition at line 144 of file csrfprotection.cpp.

◆ setup()

bool CSRFProtection::setup ( Application app)

◆ setUseSessions()

void CSRFProtection::setUseSessions ( bool  useSessions)

If this is set to true, the secret token will not be safed in a cookie but in the user's session. For this, the Session plugin has to be available.

Storing the token in a cookie (the default) is safe, but storing it in the session is common practice in other web frameworks and therefore sometimes demaned by security auditors.

Definition at line 150 of file csrfprotection.cpp.

Cutelyst Controller base class
Definition: controller.h:102
CSRFProtection(Application *parent)
Definition: csrfprotection.cpp:66