linotp.tokens.smstoken module

This file containes the dynamic sms token implementation:

  • SMSTokenClass (sms)

the SMS Token is an challenge - response token, by the means, that there is a first request, which triggers the challenge (=sending of sms message) and a second request, which refers to the initial request by the transactionid and verifies the otp value:

/validate/check_s

with params
param serial

the token serialnumber [required]

param pass

the token pin or if the token belongs to an user, the user pin/password (s. otppin policy) [required]

param data

the message, that will contain the otp value [optional] * In the message, the strings <otp>, <serial> and

<transactionid> will be replaced

  • if no data is provided, the smstext - policy value will be evaluated. Fallback is the message “<otp>”

param message

alternative name for the data parameter

return

json result wit tansaction an message, that will be displayed to the user

{
“detail”: {

“transactionid”: “172682842808”, “message”: “sms submitted”, “state”: “172682842808”

}, “version”: “LinOTP 2.7.2.1”, “jsonrpc”: “2.0”, “result”: {

“status”: true, “value”: false

}, “id”: 0

}

for the validation of the sms request now the controller method

/validate/check_t

could be used with the parameters

param pass

received otp value

param transactionid

the transactionid, which referes, that the pin has been verified and checked

alternativly the controller method

/validate/check_s

could be used as well, by providing the combination of the pin+otp in the pass parameter:

param serial

serial number of the token

param pass

the password consisting of fixed part and the otp part

return

json response

{

“version”: “LinOTP 2.7.2.1”, “jsonrpc”: “2.0”, “result”: {

“status”: true, “value”: true

}, “id”: 0

}

class linotp.tokens.smstoken.SmsTokenClass(aToken)

Bases: HmacTokenClass

implementation of the sms token class

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

checkOtp - check the otpval of a token against a given counter in the + window range

Parameters

passw (string) – the to be verified passw/pin

Returns

counter if found, -1 if not found

Return type

int

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

verify the response of a previous challenge

Parameters

  • user – the requesting user

  • passw – the to be checked pass (pin+otp)

  • options – options an additional argument, which could be token specific

  • challenges – the list of challenges, where each challenge is described as dict

Returns

tuple of (otpcounter and the list of matching challenges)

do the standard check for the response of the challenge + change the tokeninfo data of the last challenge

createChallenge(transactionid, options=None)

create a challenge, which is submitted to the user

Parameters

  • transactionid – the id of this challenge

  • options – the request context parameters / data

Returns

tuple of (bool, message and data) bool, if submit was successful message is submitted to the user data is preserved in the challenge attributes - additional attributes, which are displayed in the

output

classmethod getClassInfo(key=None, ret='all')

getClassInfo - returns all or a subtree of the token definition

Parameters

  • key (string) – subsection identifier

  • ret (user defined) – default return value, if nothing is found

Returns

subsection if key exists or user defined

:rtype : s.o.

classmethod getClassPrefix()
classmethod getClassType()

return the generic token class identifier

getInitDetail(params, user=None)

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

getNextOtp()

access the nex validf otp

Returns

otpval

Return type

string

getSMSInfo()

retrieve the phone number and the validity scope

Returns

tuple of phone number and validity time in unix lifetime sec

getUntil()

getter for the until time definition

Returns

until time definition of unix time sec

Return type

int

get_mobile_number(user=None)
get the mobile number

  • from the token info or

  • if the policy allowes it, from the user info

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

initialize the challenge - in the linotp server a challenge object has been allocated and this method is called to confirm the need of a new challenge or if for the challenge request, there is an already outstanding challenge to which then could be referred (s. ticket #2986)

Parameters

  • transactionid – the id of the new challenge

  • options – the request parameters

Returns

tuple of success - bool transid - the best transaction id for this request context message - which is shown to the user attributes - further info (dict) shown to the user

isValid()

check if sms challenge is still valid

Returns

True or False

Return type

boolean

is_challenge_request(passw, user, options=None)

check, if the request would start a challenge

  • default: if the passw contains only the pin, this request would

trigger a challenge

  • in this place as well the policy for a token is checked

Parameters

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

  • options – dictionary of additional request parameters

Returns

returns true or false

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

check, if the request contains the result of a challenge

Parameters

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

  • user – the requesting user

  • options – dictionary of additional request parameters

Returns

returns true or false

loadLinOtpSMSValidTime()

get the challenge time is in the specified range

Returns

the defined validation timeout in seconds

Return type

int

sendSMS(message=None, transactionid=None)

send sms

Parameters

message (string) – the sms submit message - could contain placeholders like <otp> or <serial>

Returns

submitted message

Return type

string

setPhone(phone)

setter for the phone number

Parameters

phone (string) – phone number

Returns

nothing

setSMSInfo(key, value)

generic method to set the sms infos like phone or validity in the tokeninfo (json) entry

Parameters

  • key (string) – name of the hash key

  • value (any) – value of the entry

Returns

nothing

setUntil(until)
This is the time the sent OTP value is valid/can be used.

(internal function)

Parameters

until (int) – until time in unix time sec

Returns

nothing

setValidUntil()

adjust the timeframe of validity

Returns

nothing

submitChallenge(options=None)

submit the sms message - former method name was checkPin

Parameters

options – the request options context

Returns

tuple of success and message

update(param, reset_failcount=True)

update - process initialization parameters

Parameters

param (dict) – dict of initialization parameters

Returns

nothing

linotp.tokens.smstoken.enforce_smstext(user='', realm='')
this function checks the boolean policy

scope=authentication, action=enforce_smstext

The function returns true if the smstext should be used instead of the challenge data :return: bool

linotp.tokens.smstoken.get_auth_smstext(user='', realm='')

this function checks the policy scope=authentication, action=smstext This is a string policy The function returns the tuple (bool, string),

bool: If a policy is defined string: the string to use

linotp.tokens.smstoken.is_phone_editable(user='')

this function checks the policy scope=selfservice, action=edit_sms This is a int policy, while the ‘0’ is a deny