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