13.2.1.2. Token Class

The following token types are known to privacyIDEA. All are inherited from the base tokenclass describe below.

class privacyidea.lib.tokenclass.TokenClass(*args, **kwds)[source]
add_init_details(*args, **kwds)[source]

(was addInfo) Adds information to a volatile internal dict

add_tokeninfo(*args, **kwds)[source]

Add a key and a value to the DB tokeninfo :param key: :param value: :return:

classmethod api_endpoint(request, g)[source]

This provides a function to be plugged into the API endpoint /ttype/<tokentype> which is defined in api/ttype.py

Parameters:
  • request – The Flask request
  • g – The Flask global object g
Returns:

Flask Response or text

authenticate(*args, **kwds)[source]

High level interface which covers the check_pin and check_otp This is the method that verifies single shot authentication like they are done with push button tokens.

It is a high level interface to support other tokens as well, which do not have a pin and otp separation - they could overwrite this method

If the authentication succeeds an OTP counter needs to be increased, i.e. the OTP value that was used for this authentication is invalidated!

Parameters:
  • passw (string) – the password which could be pin+otp value
  • user (User object) – The authenticating user
  • options (dict) – dictionary of additional request parameters
Returns:

returns tuple of 1. true or false for the pin match, 2. the otpcounter (int) and the 3. reply (dict) that will be added as

additional information in the JSON response of /validate/check.

Return type:

tuple

challenge_janitor()[source]

Just clean up all challenges, for which the expiration has expired.

Returns:None
check_auth_counter()[source]

This function checks the count_auth and the count_auth_success. If the count_auth is less than count_auth_max and count_auth_success is less than count_auth_success_max it returns True. Otherwise False.

Returns:success if the counter is less than max
Return type:bool
check_challenge_response(*args, **kwds)[source]

This method verifies if there is a matching challenge for the given passw and also verifies if the response is correct.

It then returns the new otp_counter of the token.

In case of success the otp_counter will be >= 0.

Parameters:
  • user (User object) – the requesting user
  • passw (string) – the password (pin+otp)
  • options (dict) – additional arguments from the request, which could be token specific. Usually “transactionid”
Returns:

return otp_counter. If -1, challenge does not match

Return type:

int

check_failcount()[source]

Checks if the failcounter is exceeded. It returns True, if the failcounter is less than maxfail :return: True or False

check_otp(*args, **kwds)[source]

This checks the OTP value, AFTER the upper level did the checkPIN

In the base class we do not know, how to calculate the OTP value. So we return -1. In case of success, we should return >=0, the counter

Parameters:
  • otpval – the OTP value
  • counter (int) – The counter for counter based otp values
  • window – a counter window
  • options (dict) – additional token specific options
Returns:

counter of the matching OTP value.

Return type:

int

check_otp_exist(otp, window=None)[source]

checks if the given OTP value is/are values of this very token. This is used to autoassign and to determine the serial number of a token.

Parameters:
  • otp – the OTP value
  • window (int) – The look ahead window
Returns:

True or a value > 0 in case of success

check_pin(*args, **kwds)[source]

Check the PIN of the given Password. Usually this is only dependent on the token itself, but the user object can cause certain policies.

Each token could implement its own PIN checking behaviour.

Parameters:
  • pin (string) – the PIN (static password component), that is to be checked.
  • user (User object) – for certain PIN policies (e.g. checking against the user store) this is the user, whose password would be checked. But at the moment we are checking against the userstore in the decorator “auth_otppin”.
  • options – the optional request parameters
Returns:

If the PIN is correct, return True

Return type:

bool

check_validity_period()[source]

This checks if the datetime.datetime.now() is within the validity period of the token.

Returns:success
Return type:bool
create_challenge(transactionid=None, options=None)[source]

This method creates a challenge, which is submitted to the user. The submitted challenge will be preserved in the challenge database.

If no transaction id is given, the system will create a transaction id and return it, so that the response can refer to this transaction.

Parameters:
  • transactionid – the id of this challenge
  • options (dict) – the request context parameters / data
Returns:

tuple of (bool, message, transactionid, attributes)

Return type:

tuple

The return tuple builds up like this: bool if submit was successful; message which is displayed in the JSON response; additional attributes, which are displayed in the JSON response.

del_tokeninfo(key=None)[source]
delete_token()[source]

delete the database token

enable(*args, **kwds)[source]
get_QRimage_data(response_detail)[source]

FIXME: Do we really use this?

get_as_dict()[source]

This returns the token data as a dictionary. It is used to display the token list at /token/list.

Returns:The token data as dict
Return type:dict
classmethod get_class_info(key=None, ret='all')[source]
classmethod get_class_prefix()[source]
classmethod get_class_type()[source]
get_count_auth()[source]

Return the number of all authentication tries

get_count_auth_max()[source]

Return the number of maximum allowed authentications

get_count_auth_success()[source]

Return the number of successful authentications

get_count_auth_success_max()[source]

Return the maximum allowed successful authentications

get_count_window()[source]
get_failcount()[source]
classmethod get_hashlib(hLibStr)[source]

Returns a hashlib function for a given string :param hLibStr: the hashlib :type hLibStr: string :return: the hashlib :rtype: function

get_init_detail(params=None, user=None)[source]

to complete the token normalisation, the response of the initialiastion should be build by this token specific method.

get_init_detail returns additional information after an admin/init like the QR code of an HOTP/TOTP token. Can be anything else.

Parameters:
  • params (dict) – The request params during token creation token/init
  • user (User object) – the user, token owner
Returns:

additional descriptions

Return type:

dict

get_init_details(*args, **kwds)[source]

return the status of the token rollout

Returns:return the status dict.
Return type:dict
get_max_failcount()[source]
get_multi_otp(count=0, epoch_start=0, epoch_end=0, curTime=None, timestamp=None)[source]

This returns a dictionary of multiple future OTP values of a token.

Parameters:
  • count – how many otp values should be returned
  • epoch_start – time based tokens: start when
  • epoch_end – time based tokens: stop when
  • curTime (datetime object) – current time for TOTP token (for selftest)
  • timestamp (int) – unix time, current time for TOTP token (for selftest)
Returns:

True/False, error text, OTP dictionary

Return type:

Tuple

get_otp(current_time='')[source]

The default token does not support getting the otp value will return a tuple of four values a negative value is a failure.

Returns:something like: (1, pin, otpval, combined)
get_otp_count()[source]
get_otp_count_window()[source]
get_otplen(*args, **kwds)[source]
get_pin_hash_seed()[source]
get_realms()[source]

Return a list of realms the token is assigned to :return: realms :rtype:l list

get_serial()[source]
get_sync_window()[source]
get_tokeninfo(key=None, default=None)[source]

return the complete token info or a single key of the tokeninfo. When returning the complete token info dictionary encrypted entries are not decrypted. If you want to receive a decrypted value, you need to call it directly with the key.

Parameters:
  • key (string) – the key to return
  • default (string) – the default value, if the key does not exist
Returns:

the value for the key

Return type:

int or string

get_tokentype()[source]
get_type()[source]
get_user()[source]

return the user (owner) of a token If the token has no owner assigned, we return None

Returns:The owner of the token
Return type:User object
get_user_displayname()[source]

Returns a tuple of a user identifier like user@realm and the displayname of “givenname surname”.

Returns:tuple
get_user_id()[source]
get_validity_period_end()[source]

returns the end of validity period (if set) if not set, “” is returned. :return: the end of the validity period :rtype: string

get_validity_period_start()[source]

returns the start of validity period (if set) if not set, “” is returned. :return: the start of the validity period :rtype: string

hKeyRequired = False
inc_count_auth(*args, **kwds)[source]

Increase the counter, that counts authentications - successful and unsuccessful

inc_count_auth_success(*args, **kwds)[source]

Increase the counter, that counts successful authentications

inc_failcount(*args, **kwds)[source]
inc_otp_counter(*args, **kwds)[source]

Increase the otp counter and store the token in the database :param counter: the new counter value. If counter is given, than

the counter is increased by (counter+1) If the counter is not given, the counter is increased by +1
Parameters:reset (bool) – reset the failcounter if set to True
Returns:the new counter value
is_active()[source]
is_challenge_request(*args, **kwds)[source]

This method checks, if this is a request, that triggers a challenge.

The default behaviour to trigger a challenge is, if the passw parameter only contains the correct token pin and the request contains a data or a challenge key i.e. if the options parameter contains a key data or challenge.

Each token type can decide on its own under which condition a challenge is triggered by overwriting this method.

please note: in case of pin policy == 2 (no pin is required) the check_pin would always return true! Thus each request containing a data or challenge would trigger a challenge!

The Challenge workflow is like this.

When an authentication request is issued, first it is checked if this is a request which will create a new challenge (is_challenge_request) or if this is a response to an existing challenge (is_challenge_response). In these two cases during request processing the following functions are called.

is_challenge_request or is_challenge_response

V V

create_challenge check_challenge

V V

challenge_janitor challenge_janitor

Parameters:
  • passw (string) – password, which might be pin or pin+otp
  • user (User object) – The user from the authentication request
  • options (dict) – dictionary of additional request parameters
Returns:

true or false

Return type:

bool

is_challenge_response(passw, user=None, options=None)[source]

This method checks, if this is a request, that is the response to a previously sent challenge.

The default behaviour to check if this is the response to a previous challenge is simply by checking if the request contains a parameter state or transactionid i.e. checking if the options parameter contains a key state or transactionid.

This method does not try to verify the response itself! It only determines, if this is a response for a challenge or not. The response is verified in check_challenge_response.

Parameters:
  • passw (string) – password, which might be pin or pin+otp
  • user (User object) – the requesting user
  • options (dict) – dictionary of additional request parameters
Returns:

true or false

Return type:

bool

is_locked()[source]

Check if the token is in a locked state A locked token can not be modified

Returns:True, if the token is locked.
is_previous_otp(otp, window=10)[source]

checks if a given OTP value is a previous OTP value, that lies in the past or has a lower counter.

This is used in case of a failed authentication to return the information, that this OTP values was used previously and is invalid.

Parameters:
  • otp (basestring) – The OTP value.
  • window (int) – A counter window, how far we should look into the past.
Returns:

bool

is_revoked()[source]

Check if the token is in the revoked state

Returns:True, if the token is revoked
mode = ['authenticate', 'challenge']
reset(*args, **kwds)[source]

Reset the failcounter

resync(otp1, otp2, options=None)[source]
revoke()[source]

This revokes the token. By default it 1. sets the revoked-field 2. set the locked field 3. disables the token.

Some token types may revoke a token without locking it.

save()[source]

Save the database token

set_count_auth(*args, **kwds)[source]

Sets the counter for the occurred login attepms as key “count_auth” in token info :param count: a number :type count: int

set_count_auth_max(*args, **kwds)[source]

Sets the counter for the maximum allowed login attempts as key “count_auth_max” in token info :param count: a number :type count: int

set_count_auth_success(*args, **kwds)[source]

Sets the counter for the occurred successful logins as key “count_auth_success” in token info :param count: a number :type count: int

set_count_auth_success_max(*args, **kwds)[source]

Sets the counter for the maximum allowed successful logins as key “count_auth_success_max” in token info :param count: a number :type count: int

set_count_window(*args, **kwds)[source]
set_defaults()[source]

Set the default values on the database level

set_description(*args, **kwds)[source]

Set the description on the database level

Parameters:description (string) – description of the token
set_failcount(failcount)[source]

Set the failcounter in the database

set_hashlib(*args, **kwds)[source]
set_init_details(*args, **kwds)[source]
set_maxfail(*args, **kwds)[source]
set_otp_count(*args, **kwds)[source]
set_otpkey(*args, **kwds)[source]
set_otplen(*args, **kwds)[source]
set_pin(*args, **kwds)[source]

set the PIN of a token. Usually the pin is stored in a hashed way. :param pin: the pin to be set for the token :type pin: basestring :param encrypt: If set to True, the pin is stored encrypted and

can be retrieved from the database again
set_pin_hash_seed(*args, **kwds)[source]
set_realms(realms)[source]

Set the list of the realms of a token. :param realms: realms the token should be assigned to :type realms: list

set_so_pin(*args, **kwds)[source]
set_sync_window(*args, **kwds)[source]
set_tokeninfo(*args, **kwds)[source]

Set the tokeninfo field in the DB. Old values will be deleted. :param info: dictionary with key and value :type info: dict :return:

set_type(tokentype)[source]

Set the tokentype in this object and also in the underlying database-Token-object.

Parameters:tokentype (string) – The type of the token like HOTP or TOTP
set_user(*args, **kwds)[source]

Set the user attributes (uid, resolvername, resolvertype) of a token.

Parameters:
  • user – a User() object, consisting of loginname and realm
  • report – tbdf.
Returns:

None

set_user_identifiers(*args, **kwds)[source]

(was setUid) Set the user attributes of a token :param uid: The user id in the user source :param resolvername: The name of the resolver :param resolvertype: The type of the resolver :return: None

set_user_pin(*args, **kwds)[source]
set_validity_period_end(*args, **kwds)[source]

sets the end date of the validity period for a token :param end_date: the end date in the format “%d/%m/%y %H:%M”

if the format is wrong, the method will throw an exception
set_validity_period_start(*args, **kwds)[source]

sets the start date of the validity period for a token :param start_date: the start date in the format “%d/%m/%y %H:%M”

if the format is wrong, the method will throw an exception
split_pin_pass(passw, user=None, options=None)[source]

Split the password into the token PIN and the OTP value

take the given password and split it into the PIN and the OTP value. The splitting can be dependent of certain policies. The policies may depend on the user.

Each token type may define its own way to slit the PIN and the OTP value.

Parameters:
  • passw – the password to split
  • user (User object) – The user/owner of the token
  • options (dict) – can be used be the token types.
Returns:

tuple of pin and otp value

Returns:

tuple of (split status, pin, otp value)

Return type:

tuple

status_validation_fail()[source]

callback to enable a status change, if auth failed

status_validation_success()[source]

callback to enable a status change, if auth succeeds

classmethod test_config(params=None)[source]

This method is used to test the token config. Some tokens require some special token configuration like the SMS-Token or the Email-Token. To test this configuration, this classmethod is used.

It takes token specific parameters and returns a tuple of a boolean and a result description.

Parameters:params (dict) – token specific parameters
Returns:success, description
Return type:tuple
update(param, reset_failcount=True)[source]

Update the token object

Parameters:param – a dictionary with different params like keysize, description, genkey, otpkey, pin
Type:param: dict
using_pin = True