.. java:import:: java.util Arrays

.. java:import:: java.util Collection

.. java:import:: org.apache.shiro.authc AuthenticationException

.. java:import:: org.apache.shiro.authc AuthenticationToken

.. java:import:: org.caosdb.server.utils Utils

.. java:import:: org.eclipse.jetty.util.ajax JSON

SelfValidatingAuthenticationToken
=================================

.. java:package:: org.caosdb.server.accessControl
   :noindex:

.. java:type:: public abstract class SelfValidatingAuthenticationToken extends Principal implements AuthenticationToken

   These AuthenticationTokens are characterized by the following properties:

   ..

   * date: The creation time.
   * timeout: How long this token is valid after creation.
   * checksum: The checksum is calculated from all relevant parts of the authentication token (including the salt, timeout, permissions, roles, and date) and most importantly, the pepper which serves as a randomized password of the server. The salt makes it hard to guess the pepper by creating a rainbow table with plausible values for the other properties.
   * salt: Salt for the password checksum, may be used by inheriting classes.
   * pepper: A static property, generated when class is loaded and used until the server reboots. It servers as randomized password of the server. "In cryptography, a pepper is a secret added to an input such as a password prior to being hashed with a cryptographic hash function." (from: Pepper (cryptography), https://en.wikipedia.org/w/index.php?title=Pepper_(cryptography)&oldid=960047694 (last visited July 7, 2020)) In our case, the pepper is added to the token before hashing, but not exposed to the public, while the salt is. That also means that the resulting hash cannot be generated by any client nor be validated by any client, and that all tokens of this kind invalidate when the server reboots.

Fields
------
PEPPER
^^^^^^

.. java:field:: protected static final transient String PEPPER
   :outertype: SelfValidatingAuthenticationToken

checksum
^^^^^^^^

.. java:field:: protected final String checksum
   :outertype: SelfValidatingAuthenticationToken

date
^^^^

.. java:field:: protected final long date
   :outertype: SelfValidatingAuthenticationToken

permissions
^^^^^^^^^^^

.. java:field:: protected final String[] permissions
   :outertype: SelfValidatingAuthenticationToken

roles
^^^^^

.. java:field:: protected final String[] roles
   :outertype: SelfValidatingAuthenticationToken

salt
^^^^

.. java:field:: protected final String salt
   :outertype: SelfValidatingAuthenticationToken

timeout
^^^^^^^

.. java:field:: protected final long timeout
   :outertype: SelfValidatingAuthenticationToken

Constructors
------------
SelfValidatingAuthenticationToken
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. java:constructor:: public SelfValidatingAuthenticationToken(Principal principal, long date, long timeout, String salt, String checksum, String[] permissions, String[] roles)
   :outertype: SelfValidatingAuthenticationToken

SelfValidatingAuthenticationToken
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. java:constructor:: public SelfValidatingAuthenticationToken(Principal principal, long timeout, String[] permissions, String[] roles, Object... fields)
   :outertype: SelfValidatingAuthenticationToken

Methods
-------
calcChecksum
^^^^^^^^^^^^

.. java:method:: public final String calcChecksum()
   :outertype: SelfValidatingAuthenticationToken

calcChecksum
^^^^^^^^^^^^

.. java:method:: public abstract String calcChecksum(String pepper)
   :outertype: SelfValidatingAuthenticationToken

   Implementation specific version of a peppered checksum.

   For secure operation, implementing classes must make sure that the pepper is actually used in calculating the checksum and that the checksum can not be used to infer information about the pepper. This can be achieved for example by using the \ :java:ref:`calcChecksum(finalObject...fields)`\  method.

calcChecksum
^^^^^^^^^^^^

.. java:method:: protected static String calcChecksum(Object... fields)
   :outertype: SelfValidatingAuthenticationToken

   Return the hash (SHA512) of the stringified arguments.

defaultIfNull
^^^^^^^^^^^^^

.. java:method:: protected static <T> T defaultIfNull(T val, T def)
   :outertype: SelfValidatingAuthenticationToken

getCredentials
^^^^^^^^^^^^^^

.. java:method:: @Override public Object getCredentials()
   :outertype: SelfValidatingAuthenticationToken

   No credentials (returns null), since this token is self-validating.

getExpires
^^^^^^^^^^

.. java:method:: public long getExpires()
   :outertype: SelfValidatingAuthenticationToken

getFreshSalt
^^^^^^^^^^^^

.. java:method:: public static final String getFreshSalt()
   :outertype: SelfValidatingAuthenticationToken

getPermissions
^^^^^^^^^^^^^^

.. java:method:: public Collection<String> getPermissions()
   :outertype: SelfValidatingAuthenticationToken

getPrincipal
^^^^^^^^^^^^

.. java:method:: @Override public SelfValidatingAuthenticationToken getPrincipal()
   :outertype: SelfValidatingAuthenticationToken

   No "other" identity, so this returns itself.

getRoles
^^^^^^^^

.. java:method:: public Collection<String> getRoles()
   :outertype: SelfValidatingAuthenticationToken

getTimeout
^^^^^^^^^^

.. java:method:: public long getTimeout()
   :outertype: SelfValidatingAuthenticationToken

isExpired
^^^^^^^^^

.. java:method:: public boolean isExpired()
   :outertype: SelfValidatingAuthenticationToken

isHashValid
^^^^^^^^^^^

.. java:method:: public boolean isHashValid()
   :outertype: SelfValidatingAuthenticationToken

   Test if the hash stored in `checksum` is equal to the one calculated using the secret pepper.

isValid
^^^^^^^

.. java:method:: public boolean isValid()
   :outertype: SelfValidatingAuthenticationToken

parse
^^^^^

.. java:method:: public static SelfValidatingAuthenticationToken parse(String token)
   :outertype: SelfValidatingAuthenticationToken

   Parse a JSON string and return the generated token. Depending on the first element of the JSON, this is either (if it is "O") a OneTimeAuthenticationToken or (if it is "S") a SessionToken.

   :throws AuthenticationToken: if the string could not be parsed into a token.

setFields
^^^^^^^^^

.. java:method:: protected abstract void setFields(Object[] fields)
   :outertype: SelfValidatingAuthenticationToken

   Customizable customization method, will be called with the remaining constructor arguments.

toString
^^^^^^^^

.. java:method:: @Override public abstract String toString()
   :outertype: SelfValidatingAuthenticationToken

toStringArray
^^^^^^^^^^^^^

.. java:method:: protected static String[] toStringArray(Object[] array)
   :outertype: SelfValidatingAuthenticationToken