13.2.1.2. Token Class¶
The following token types are known to privacyIDEA. All are inherited from the base tokenclass describe below.
- 13.2.1.2.1. 4 Eyes Token
- 13.2.1.2.2. Certificate Token
- 13.2.1.2.3. Daplug Token
- 13.2.1.2.4. Email Token
- 13.2.1.2.5. HOTP Token
- 13.2.1.2.6. mOTP Token
- 13.2.1.2.7. PasswordToken
- 13.2.1.2.8. RADIUS Token
- 13.2.1.2.9. Registration Code Token
- 13.2.1.2.10. Remote Token
- 13.2.1.2.11. SMS Token
- 13.2.1.2.12. SPass Token
- 13.2.1.2.13. SSHKey Token
- 13.2.1.2.14. TiQR Token
- 13.2.1.2.15. TOTP Token
- 13.2.1.2.16. U2F Token
- 13.2.1.2.17. Yubico Token
- 13.2.1.2.18. Yubikey Token
-
class
privacyidea.lib.tokenclass.
TokenClass
(*args, **kwds)[source]¶ -
-
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; additionalattributes
, which are displayed in the JSON response.
-
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_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_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_realms
()[source]¶ Return a list of realms the token is assigned to :return: realms :rtype:l list
-
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_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_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_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 +1Parameters: reset (bool) – reset the failcounter if set to True Returns: the new counter value
-
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 adata
or achallenge
key i.e. if theoptions
parameter contains a keydata
orchallenge
.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 adata
orchallenge
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
ortransactionid
i.e. checking if theoptions
parameter contains a keystate
ortransactionid
.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']¶
-
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.
-
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_description
(*args, **kwds)[source]¶ Set the description on the database level
Parameters: description (string) – description of the token
-
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_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_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_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
-
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¶
-