Implementation of one-time CSRF-security-keys.

CSRF-security-keys (Cross-Site Request Forgery) are used mostly to make requests unique and non-reproducible. Doing the same request again requires to obtain a fresh security key first. Furthermore, security keys can be used to implemented credential-reset mechanisms or similar features, where a URL is only valid for one call.


There’s also a hidden 3rd type of security-key: The session’s static security key.

This key is only revealed once during login, as the protected header “Sec-X-ViUR-StaticSessionKey”.

This can be used instead of the one-time sessions security key by sending it back as the same protected HTTP header and setting the skey value to “STATIC_SESSION_KEY”. This is only intended for non-web-browser, programmatic access (admin tools, import tools etc.) where CSRF attacks are not applicable.

Therefor that header is prefixed with “Sec-” - so it cannot be read or set using JavaScript.

Module Contents


create([duration, session_bound, key_length, indexed])

Creates a new one-time CSRF-security-key.

validate(key[, session_bound])

Validates a CSRF-security-key.







The name of the header in which the static session key is provided at login


Value that must be used as a marker in the payload (key: skey) to indicate

core.securitykey.SECURITYKEY_KINDNAME = 'viur-securitykey'
core.securitykey.SECURITYKEY_STATIC_HEADER: Final[str] = 'Sec-X-ViUR-StaticSessionKey'

The name of the header in which the static session key is provided at login and must be specified in requests that require a skey.


Value that must be used as a marker in the payload (key: skey) to indicate that the session key from the headers should be used.

core.securitykey.create(duration=None, session_bound=True, key_length=13, indexed=True, **custom_data)

Creates a new one-time CSRF-security-key.

The custom data (given as **custom_data) that can be stored with the key. Any data provided must be serializable by the datastore.

  • duration (None | int | datetime.timedelta) – Make this CSRF-token valid for a fixed timeframe.

  • session_bound (bool) – Bind this CSRF-token to the current session.

  • indexed (bool) – Indexes all values stored with the security-key (default), set False to not index.

  • custom_data – Any other data is stored with the CSRF-token, for later re-use.

  • key_length (int) –


The new one-time key, which is a randomized string.

Return type:


core.securitykey.validate(key, session_bound=True)

Validates a CSRF-security-key.

  • key (str) – The CSRF-token to be validated.

  • session_bound (bool) – If True, make sure the CSRF-token is created inside the current session.


False if the key was not valid for whatever reasons, the data (given during create()) as dictionary or True if the dict is empty (or session was True).

Return type:

bool | viur.core.db.Entity