core.securitykey

This module provides one-time keys.

There are two types of security keys:

  1. If :meth:create is called without arguments, it returns the current session CSRF token. Repeated calls to

    :meth:create will return the same CSRF token (for the same session) until that token has been redeemed. This security key will be valid as long the session is active, and it’s not possible to store data along with that key. These are usually used as a CSRF token. This has been changed from ViUR2 - where it was possible to create a arbitrary number of security keys per session.

  2. If :meth:create is called with a duration (and optional kwargs values), it will create a security key

    that is not bound to the current session, but it’s possible to store custom data (provided by kwargs). As these are not bound to the session, each call to :meth:create will yield a new token. These are used if it’s expected that the token may be redeemed on a different device (e.g. when sending an email address confirmation)

..note:

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

This key is only revealed once (during login, as the protected header Sec-X-ViUR-StaticSKey).

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 “staticSessionKey”. 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

Functions

create(→ str)

Creates a new one-time security key or returns the current sessions CSRF-token.

validate(→ Union[bool, viur.core.db.Entity])

Validates a security key.

start_clear_skeys()

Removes old (expired) skeys

Attributes

SECURITYKEY_KINDNAME

core.securitykey.SECURITYKEY_KINDNAME = 'viur-securitykey'
core.securitykey.create(duration: None | int = None, **custom_data) → str

Creates a new one-time security key or returns the current sessions CSRF-token.

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

Parameters:

duration – Make this key valid for a fixed timeframe of seconds (and independent of the current session)

Returns:

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

core.securitykey.validate(key: str, useSessionKey: bool) → bool | viur.core.db.Entity

Validates a security key.

If useSessionKey is True, the key is expected to be the session’s current security key or its static security key.

Otherwise, it must be a key created with a duration, so that it is session independent.

Parameters:

  • key – The key to be validated

  • useSessionKey – If True, validate against the session’s skey, otherwise lookup an unbound key

Returns:

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

core.securitykey.start_clear_skeys()

Removes old (expired) skeys