15.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(db_token)[source]
add_init_details(key, value)[source]

(was addInfo) Adds information to a volatile internal dict

add_tokeninfo(key, value, value_type=None)[source]

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

add_user(user, report=None)[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

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

The method should return

return “json”, {}

or

return “text”, “OK”

Parameters
  • request – The Flask request

  • g – The Flask global object g

Returns

Flask Response or text

authenticate(passw, user=None, options=None)[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

static challenge_janitor()[source]

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

Returns

None

check_all(message_list)[source]

Perform all checks on the token. Returns False if the token is either: * auth counter exceeded * not active * fail counter exceeded * validity period exceeded

This is used in the function token.check_token_list

Parameters

message_list – A list of messages

Returns

False, if any of the checks fail

check_auth_counter()[source]

This function checks the count_auth and the count_auth_success. If the counters are less or equal than the maximum allowed counters it returns True. Otherwise False.

Returns

success if the counter is less than max

Return type

bool

check_challenge_response(user=None, passw=None, options=None)[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_last_auth_newer(last_auth)[source]

Check if the last successful authentication with the token is newer than the specified time delta which is passed as 10h, 7d or 1y.

It returns True, if the last authentication with this token is newer* than the specified delta.

Parameters

last_auth (basestring) – 10h, 7d or 1y

Returns

bool

check_otp(otpval, counter=None, window=None, options=None)[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(pin, user=None, options=None)[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_reset_failcount()[source]

Checks if we should reset the failcounter due to the FAILCOUNTER_CLEAR_TIMEOUT

Returns

True, if the failcounter was resetted

check_validity_period()[source]

This checks if the 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.

static decode_otpkey(otpkey, otpkeyformat)[source]

Decode the otp key which is given in a specific format.

Supported formats:
  • hex, in which the otpkey is returned verbatim

  • base32check, which is specified in decode_base32check

In case the OTP key is malformed or if the format is unknown, a ParameterError is raised.

Parameters
  • otpkey – OTP key passed by the user

  • otpkeyformat – “hex” or “base32check”

Returns

hex-encoded otpkey

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

delete the database token

enable(enable=True)[source]
generate_symmetric_key(server_component, client_component, options=None)[source]

This method generates a symmetric key, from a server component and a client component. This key generation could be based on HMAC, KDF or even Diffie-Hellman.

The basic key-generation is simply replacing the last n byte of the server component with bytes of the client component.

Parameters
  • server_component (str) – The component usually generated by privacyIDEA. This is a hex string

  • client_component (str) – The component usually generated by the client (e.g. smartphone). This is a hex string.

  • options

Returns

the new generated key as hex string

Return type

str

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

static get_class_info(key=None, ret='all')[source]
static get_class_prefix()[source]
static 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]
classmethod get_default_settings(g, params)[source]

This method returns a dictionary with default settings for token enrollment. These default settings depend on the token type and the defined policies.

The returned dictionary is added to the parameters of the API call. :param g: context object, see documentation of Match :param params: The call parameters :type params: dict :return: default parameters

get_failcount()[source]
static get_hashlib(hLibStr)[source]

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

static get_import_csv(l)[source]

Read the list from a csv file and return a dictionary, that can be used to do a token_init.

Parameters

l (list) – The list of the line of a csv file

Returns

A dictionary of init params

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

to complete the token initialization, the response of the initialisation should be build by this token specific method. This method is called from api/token after the token is enrolled

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()[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()[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]
static get_setting_type(key)[source]

This function returns the type of the token specific config/setting. This way a tokenclass can define settings, that can be “public” or a “password”. If this setting is written to the database, the type of the setting is set automatically in set_privacyidea_config

The key name needs to start with the token type.

Parameters

key – The token specific setting key

Returns

A string like “public”

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_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()[source]

Increase the counter, that counts authentications - successful and unsuccessful

inc_count_auth_success()[source]

Increase the counter, that counts successful authentications Also increase the auth counter

inc_failcount()[source]
inc_otp_counter(counter=None, increment=1, reset=True)[source]

Increase the otp counter and store the token in the database

Before increasing the token.count the token.count can be set using the parameter counter.

Parameters
  • counter (int) – if given, the token counter is first set to counter and then increased by increment

  • increment (int) – increase the counter by this amount

  • reset (bool) – reset the failcounter if set to True

Returns

the new counter value

is_active()[source]
is_challenge_request(passw, user=None, options=None)[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_fit_for_challenge(messages, options=None)[source]

This method is called if a cryptographically matching response to a challenge was found. This method may implement final checks, if there is anything that should deny the success of the authentication with the response to the challenge.

The options dictionary can also contain the transaction_id, so even the challenge table for this token can be used for checking.

Parameters
  • options (dict) –

  • messages (list) – This is a list of messages. This method can append new information to this message list.

Returns

True or False

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_orphaned()[source]

Return True if the token is orphaned.

An orphaned token means, that it has a user assigned, but the user does not exist in the user store (anymore) :return: True / False

classmethod is_outofband()[source]
is_pin_change(password=False)[source]

Returns true if the pin of the token needs to be changed. :param password: Whether the password needs to be changed. :type password: bool

Returns

True or False

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()[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(count)[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(count)[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(count)[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(count)[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(countWindow)[source]
set_defaults()[source]

Set the default values on the database level

set_description(description)[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(hashlib)[source]
set_init_details(details)[source]
set_maxfail(maxFail)[source]
set_next_pin_change(diff=None, password=False)[source]

Sets the timestamp for the next_pin_change. Provide a difference like 90d (90 days).

Either provider the :param diff: The time delta. :type diff: basestring :param password: Do no set next_pin_change but next_password_change :return: None

set_otp_count(otpCount)[source]
set_otpkey(otpKey)[source]
set_otplen(otplen)[source]
set_pin(pin, encrypt=False)[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(pinhash, seed)[source]
set_realms(realms, add=False)[source]

Set the list of the realms of a token. :param realms: realms the token should be assigned to :type realms: list :param add: if the realms should be added and not replaced :type add: boolean

set_so_pin(soPin)[source]
set_sync_window(syncWindow)[source]
set_tokeninfo(info)[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_pin(userPin)[source]
set_validity_period_end(end_date)[source]

sets the end date of the validity period for a token :param end_date: the end date in the format YYYY-MM-DDTHH:MM+OOOO

if the format is wrong, the method will throw an exception

set_validity_period_start(start_date)[source]

sets the start date of the validity period for a token :param start_date: the start date in the format YYYY-MM-DDTHH:MM+OOOO

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

static 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

property user

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 or None

using_pin = True