linotp.tokens.base package

This file containes the standard token definitions:

the base class “TokenClass”, that you may use to define your own tokenclasses.

You can add your own Tokens by adding the modules comma seperated to the directive ‘TOKEN_MODULES’ in a linotp.cfg file.

exception linotp.tokens.base.InvalidSeedException(msg)

Bases: Exception

class linotp.tokens.base.TokenClass(token)

Bases: TokenPropertyMixin, TokenValidityMixin

addToInfo(key, value)
addToSession()
authenticate(passw, user, options=None)

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 as well other tokens, which do not have a pin and otp seperation - they could overwrite this method

remarks: we have to call the global methods (check_pin,++) as they take the pin policies into account

Parameters

  • passw (string) – the passw which could be pin+otp

  • user (User object) – The authenticating user

  • options ((dict)) – dictionary of additional request parameters

Returns

returns tuple true or false for the pin match, the otpcounter (int) and the reply (dict) that will be added as additional information in the JSON response of /validate/check.

challenge_janitor(matching_challenges, challenges)

This is the default janitor for the challenges of a token.

The idea is to delete all challenges, which have an id lower than the matching one. Other janitors could be implemented on a token base and overwrite this behaviour.

Remarks: In later versions this will be the place to hook a dynamically loaded default token specific janitor.

Parameters

  • matching_challenges (list) – the last matching challenge

  • challenges (list) – all current challenges

Returns

list of all challenges, which should be deleted

checkOtp(anOtpVal1, counter, window, options=None)

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

return:

counter of the matching OTP value.

checkPin(pin, options=None)

checkPin - test is the pin is matching

Parameters

  • pin – the pin

  • options – additional optional parameters, which could be token specific

Returns

boolean

checkResponse4Challenge(user, passw, options=None, challenges=None)

This method verifies if the given passw matches any existing challenge of the token.

It then returns the new otp_counter of the token and the list of the matching challenges.

In case of success the otp_counter needs to be > 0. The matching_challenges is passed to the method challenge_janitor() to clean up challenges.

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

  • challenges (list) – A sorted list of valid challenges for this token.

Returns

tuple of (otpcounter and the list of matching challenges)

check_authenticate(user, passw, options=None)

simple authentication with pin+otp

Parameters

  • passw – the password, which should be checked

  • options – dict with additional request parameters

Returns

tuple of matching otpcounter and a potential reply

check_challenge_response(challenges, user, passw, options=None)

This function checks, if the given response (passw) matches any of the open challenges

to prevent the token author to deal with the database layer, the token.checkResponse4Challenge will recieve only the dictionary of the challenge data

Parameters

  • challenges – the list of database challenges

  • user – the requesting use

  • passw – the to password of the request, which must be pin+otp

  • options – the addtional request parameters

Returns

tuple of otpcount (as result of an internal token.checkOtp) and additional optional reply

check_otp_exist(otp, window=None, user=None, autoassign=False)

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.

check_standard(passw, user, options=None)

do a standard verification, as we are not in a challengeResponse mode

the upper interfaces expect in the success the otp counter or at least 0 if we have a success. A -1 identifies an error

Parameters

  • passw – the password, which should be checked

  • options – dict with additional request parameters

Returns

tuple of matching otpcounter and a potential reply

check_token(passw, user, options=None, challenges=None)

validate a token against the provided pass

Raises

“challenge not found”, if a state is given and no challenge is found for this challenge id

Parameters

  • passw – the password, which could either be a pin, a pin+otp or otp

  • user – the user which the token belongs to

  • options – dict with additional request parameters

  • challenges –

Returns

tuple of otpcounter and potential reply

static copy_pin(src, target)
createChallenge(transactionid, options=None)

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

This method is called after the method initChallenge().

Parameters

  • transactionid – the id of this challenge

  • options (dict) – the request context parameters / data

Returns

tuple of (bool, message, data, attributes)

The return tuple builds up like this:

bool if submit was successfull; message which is displayed in the JSON response; data is preserved in the challenge; additional attributes, which are displayed in the JSON response.

deleteToken()
enable(enable)
flush()
getAuthDetail()
getChallengePrompt(default='Otp:')

The customizable prompt for the challenge

The prompt for the challenge of every token type can be declared in the config with the corresponding token type name (in capitals) and concatanted by “_CHALLENGE_PROMPT”. e.g. SMS_CHALLENGE_PROMPT, EMAIL_CHALLENGE_PROMPT etc

classmethod getClassPrefix()
classmethod getClassType()
getCounterWindow()
getDescription()

set the token description :param description: set the token description

getFailCount()
getHashlib(hLibStr)
getInfo()

getInfo - return the status of the token rollout

Returns

return the status dict.

Return type

dict

getInitDetail(params, user=None)

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

getMaxFailCount()
getOfflineInfo()
getOtp(curtTime='')

The default token does not support getting the otp value will return something like:

1, pin, otpval, combined

a negative value is a failure.

getOtpCount()
getOtpCountWindow()
getOtpLen()
getPin()
Returns

the value of the pin- if it is stored encrypted

getQRImageData(response_detail)
getRealms()
getSerial()
getSyncWindow()
getType()
getUser()

get the user info of the token

Returns

tuple of user id, user resolver and resolver class

getUserId()
getUsername()

get the username of the token owner

Returns:

str: username

get_challenge_validity()

This method returns the token specific challenge validity

Returns

int - validity in seconds

get_enrollment_status()
classmethod get_helper_params_post(params, user)

hook method which gets called with the parameters given to admin/init and the user that possibly gets created from it. It returns a dictionary which will be added to the helper_params. In contrast to get_helper_params_pre this function will be called _after_ the user object gets created from the parameters

Params params

the request parameters supplied to admin/init

Params user

the user object created from the request parameters (None if no user was specified in the request)

Returns

dictionary with additional helper params

classmethod get_helper_params_pre(params)

hook method which gets called with the parameters given to admin/init and returns a dictionary which will be added to the helper_params. In contrast to get_helper_params_post this function will be called _before_ the user object gets created from the parameters

Params params

the request parameters supplied to admin/init

Returns

dictionary with additional helper params

get_multi_otp(count=0, epoch_start=0, epoch_end=0, curTime=None)

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

parameter

count - how many otp values should be returned epoch_start - time based tokens: start when epoch_end - time based tokens: stop when

return

True/False error text OTP dictionary

Returns

list of related challenges

get_token_realm_user()
get_vars(save=False)

return the token state as dicts :return: token as dict

get_verification_result()

return the internal result representation of the token verification which are a set of list, which stand for the challenge, pinMatching or invalid or valid token list

  • the lists are returned as they easily could be joined into the final token list, independent of they are empty or contain a token obj

Returns

tuple of token lists

incOtpCounter(counter=None, reset=True)
method

incOtpCounter(aToken, counter)

parameters:

token - a token object counter - the new counter reset - optional -

exception:

in case of an transaction fail an exception is thrown

side effects:

default of reset will reset the failCounter

incOtpFailCounter()
initChallenge(transactionid, challenges=None, options=None)

This method initializes the challenge.

This is a hook that is called before the method createChallenge(), which will only be called if this method returns success==true.

Thus this method can be used, to verify if there is an outstanding challenge or if a new challenge needs to be created. E.g. this hook can be used, to implement a blocking mechanism to allow the creation of a new challenge only after a certain timeout. If there is an already outstanding challenge the return value can refer to this. (s. ticket #2986)

Parameters

  • transactionid (string) – the id of the new challenge

  • options (dict) – the request parameters

  • challenges (list) – a list of all valid challenges for this token.

Returns

tuple of ( success, transid, message, additional attributes )

The transid (the best transaction id for this request context), message, and additional attributes (dictionar) are displayed as results in the JSON response of the /validate/check request.

Only in case of success == true the next method createChallenge will be called.

isActive()
is_auth_only_token(user)

check if token is in the authenticate only mode this is required to optimize the number of requests

Parameters

user – the user / realm where the token policy is applied

Returns

boolean

is_challenge_and_auth_token(user)
check if token supports both authentication methods:

authenticate an challenge responser

Parameters

user – the user / realm where the token policy is applied

Returns

boolean

is_challenge_request(passw, user, options=None)

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!

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

is_challenge_response(passw, user, options=None, challenges=None)

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.

Parameters

  • passw (string) – password, which might be pin or pin+otp

  • user (User object) – the requesting user

  • options ((dict)) – dictionary of additional request parameters

  • challenges – A list of challenges for this token. These challenges may be used, to identify if this request is a response for a challenge.

Returns

true or false

pair(response_data)
reset()

reset the token failcount value

resetTokenInfo()

base token api - could be overwritten per token

resync(otp1, otp2, options=None)
setCounterWindow(countWindow)
setDefaults()
setDescription(description)

set the token description :param description: set the token description

setFailCount(failCount)
setHashLib(hashlib)
setInfo(info)
setMaxFail(maxFail)
setOtpCount(otpCount)
setOtpKey(otpKey, reset_failcount=True)
set the token seed / secret

the seed / secret is encrypted and the encrypte value is stored in the Token model

Parameters

  • otpKey – the token seed / secret

  • reset_failcount – boolean, if the failcounter should be reseted

setOtpLen(otplen)
setPin(pin, param=None)

set the PIN. The optional parameter “param” can hold the information, if the PIN is encrypted or hashed.

Parameters

  • pin – the pin value

  • param – the additional request parameters, which could contain the ‘encryptpin’ value, that triggers, that the token secret are stored in an encrypted form

Returns

  • nothing -

setRealms(realms)
setSoPin(soPin)
set the soPin of the token

the soPin is encrypted and the encrypte value is stored in the Token model

Parameters

soPin – the special so pin

setSyncWindow(syncWindow)
setType(typ)
setUid(uid, uidResolver, uidResClass)

sets the UID values in the database

setUser(user, report)
Parameters

  • user – a User() object, consisting of loginname and realm

  • report – tbdf.

setUserPin(userPin)
set the userPin of the token

the userPin is encrypted and the encrypte value is stored in the Token model

Parameters

userPin – the user pin

splitPinPass(passw)
statusValidationFail()

callback to enable a status change, when authentication failed

statusValidationSuccess()

callback to enable a status change, on authentication success

storeToken()
unpair()
update(param, reset_failcount=True)
validate_seed(seed)

Check if the seed string contains only valid characters. Specific token classes should override this method, otherwise no validation occurs.

Parameters

seed – a string that should be checked for

validity as a seed (aka otpkey)