core.securitykey
================

.. py:module:: core.securitykey

.. autoapi-nested-parse::

   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.

   ..note:
       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.



Attributes
----------

.. autoapisummary::

   core.securitykey.SECURITYKEY_KINDNAME
   core.securitykey.SECURITYKEY_DURATION
   core.securitykey.SECURITYKEY_STATIC_HEADER
   core.securitykey.SECURITYKEY_STATIC_SKEY


Functions
---------

.. autoapisummary::

   core.securitykey.create
   core.securitykey.validate
   core.securitykey.periodic_clear_skeys
   core.securitykey.clear_session_skeys


Module Contents
---------------

.. py:data:: SECURITYKEY_KINDNAME
   :value: 'viur-securitykey'


.. py:data:: SECURITYKEY_DURATION
   :value: 86400


.. py:data:: SECURITYKEY_STATIC_HEADER
   :type:  Final[str]
   :value: '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.


.. py:data:: SECURITYKEY_STATIC_SKEY
   :type:  Final[str]
   :value: 'STATIC_SESSION_KEY'


   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.


.. py:function:: 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.

   :param duration: Make this CSRF-token valid for a fixed timeframe.
   :param session_bound: Bind this CSRF-token to the current session.
   :param indexed: Indexes all values stored with the security-key (default), set False to not index.
   :param custom_data: Any other data is stored with the CSRF-token, for later re-use.

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


.. py:function:: validate(key, session_bound = True)

   Validates a CSRF-security-key.

   :param key: The CSRF-token to be validated.
   :param session_bound: If True, make sure the CSRF-token is created inside the current session.
   :returns: False if the key was not valid for whatever reasons, the data (given during :meth:`create`) as
       dictionary or True if the dict is empty (or session was True).


.. py:function:: periodic_clear_skeys()

.. py:function:: clear_session_skeys(session_key)