This module contains all top level token functions. It depends on the models, lib.user and lib.tokenclass (which depends on the tokenclass implementations like lib.tokens.hotptoken)
This is the middleware/glue between the HTTP API and the database
Sets a token info field in the database. The info is a dict for each token of key/value pairs.
Parameters: |
|
---|
is stored encrypted :type value_type: basestring :param user: The owner of the tokens, that should be modified :type user: User object :return: the number of modified tokens :rtype: int
Produce a conjunction of expressions joined by AND.
E.g.:
from sqlalchemy import and_
stmt = select([users_table]).where(
and_(
users_table.c.name == 'wendy',
users_table.c.enrolled == True
)
)
The and_() conjunction is also available using the Python & operator (though note that compound expressions need to be parenthesized in order to function with Python operator precedence behavior):
stmt = select([users_table]).where(
(users_table.c.name == 'wendy') &
(users_table.c.enrolled == True)
)
The and_() operation is also implicit in some cases; the Select.where() method for example can be invoked multiple times against a statement, which will have the effect of each clause being combined using and_():
stmt = select([users_table]).\
where(users_table.c.name == 'wendy').\
where(users_table.c.enrolled == True)
See also
or_()
Assign token to a user. If the PIN is given, the PIN is reset.
Parameters: |
|
---|---|
Returns: | True if the token was assigned, in case of an error an exception |
is thrown :rtype: bool
This function is called to auto_assign a token to the user.
If the user does not have a token, yet, the not assigned tokens in his realm are searched if they match the given passw.
Parameters: |
|
---|---|
Returns: | True or False and detailed reply information |
Return type: | bool, dict |
This checks, if the given serial number can be used for a new token. it returns a tuple (result, new_serial) result being True if the serial does not exist, yet. new_serial is a suggestion for a new serial number, that does not exist, yet.
Parameters: | serial – Seral number that is to be checked, if it can be used for |
---|
a new token. :type serial: string :result: bool and serial number :rtype: tuple
This function checks the otp for a given serial
If the OTP matches, True is returned and the otp counter is increased.
The function tries to determine the user (token owner), to derive possible additional policies from the user.
Parameters: |
|
---|---|
Returns: | tuple of result (True, False) and additional dict |
Return type: | tuple |
this takes a list of token objects and tries to find the matching token for the given passw. In also tests, * if the token is active or * the max fail count is reached, * if the validity period is ok...
This function is called by check_serial_pass, check_user_pass and check_yubikey_pass.
Parameters: |
|
---|---|
Returns: | tuple of success and optional response |
Return type: | (bool, dict) |
This function checks the otp for a given user. It is called by the API /validate/check and simplecheck
If the OTP matches, True is returned and the otp counter is increased.
Parameters: |
|
---|---|
Returns: | tuple of result (True, False) and additional dict |
Return type: | tuple |
This function copies the token PIN from one token to the other token. This can be used for workflows like lost token.
In fact the PinHash and the PinSeed are transferred
Parameters: |
|
---|---|
Returns: | True. In case of an error raise an exception |
Return type: | bool |
Copy the realms of one token to the other token
Parameters: |
|
---|---|
Returns: | None |
This function copies the user from one token to the other token. In fact the user_id, resolver and resolver type are transferred.
Parameters: |
|
---|---|
Returns: | True. In case of an error raise an exception |
Return type: | bool |
(was createTokenClassObject) create a token class object from a given type If a tokenclass for this type does not exist, the function returns None.
Parameters: | db_token (database token object) – the database referenced token |
---|---|
Returns: | instance of the token class object |
Return type: | tokenclass object |
Enable or disable a token. This can be checked with is_token_active
Enabling an already active token will return 0.
Parameters: |
|
---|---|
Returns: | Number of tokens that were enabled/disabled |
Return type: |
generate a serial for a given tokentype
Parameters: |
|
---|---|
Returns: | serial number |
Return type: | string |
return a dictionary with all tokens, that are assigned to users. This returns a dictionary with the key being the serial number of the token and the user information as dict.
Returns: | dictionary of serial numbers |
---|---|
Return type: | dict |
This returns the dynamic policy definitions that come with the new loaded token classes.
Parameters: | scope – an optional scope parameter. Only return the policies of |
---|
this scope. :return: The policy definition for the token or only for the scope.
This function returns a list of OTP values for the given Token. Please note, that the tokentype needs to support this function.
Parameters: |
|
---|
time based tokens) :param epoch_start: unix time start date (used with time based tokens) :param epoch_end: unix time end date (used with time based tokens) :param curTime: Simulate the servertime :type curTime: datetime :param timestamp: Simulate the servertime (unix time in seconds) :type timestamp: int
Returns: | dictionary of otp values |
---|---|
Return type: | dictionary |
This returns the number of tokens in one realm. :param realm: The name of the realm :type realm: basestring :param active: If only active tokens should be taken into account :type active: bool :return: The number of tokens in the realm :rtype: int
This function returns the current OTP value for a given Token. The tokentype needs to support this function. if the token does not support getting the OTP value, a -2 is returned.
Parameters: |
|
---|---|
Returns: | tuple with (result, pin, otpval, passw) |
Return type: | tuple |
This function returns a list of the realms of a token
Parameters: | serial (basestring) – the serial number of the token |
---|---|
Returns: | list of the realm names |
Return type: | list |
Returns the serial for a given OTP value The tokenobject_list would be created by get_tokens()
Parameters: |
|
---|---|
Returns: | the serial for a given OTP value and the user |
Return type: | basestring |
search the token in the token_list, that creates the given OTP value. The tokenobject_list would be created by get_tokens()
Parameters: |
|
---|---|
Returns: | The token, that creates this OTP value |
Return type: | Tokenobject |
returns the user object, to which the token is assigned. the token is identified and retrieved by it’s serial number
If the token has no owner, None is returned
Parameters: | serial (basestring) – serial number of the token |
---|---|
Returns: | The owner of the token |
Return type: | User object or None |
Returns the tokentype of a given serial number
Parameters: | serial (string) – the serial number of the to be searched token |
---|---|
Returns: | tokentype |
Return type: | string |
return the config definition of a dynamic token
Parameters: |
|
---|---|
Returns: | dict - if nothing found an empty dict |
Return type: | dict |
(was getTokensOfType) This function returns a list of token objects of a * given type, * of a realm * or tokens with assignment or not * for a certain serial number or * for a User
E.g. thus you can get all assigned tokens of type totp.
Parameters: |
|
---|
If None get all tokens. :type assigned: bool :param user: Filter for the Owner of the token :type user: User Object :param serial: The serial number of the token :type serial: basestring :param active: Whether only active (True) or inactive (False) tokens should be returned :type active: bool :param resolver: filter for the given resolver name :type resolver: basestring :param rollout_state: returns a list of the tokens in the certain rollout state. Some tokens are not enrolled in a single step but in multiple steps. These tokens are then identified by the DB-column rollout_state. :param count: If set to True, only the number of the result and not the list is returned. :type count: bool
Returns: | A list of tokenclasses (lib.tokenclass) |
---|---|
Return type: | list |
Return a list of the token ojects, that contain this very resolver
Parameters: | resolver (basestring) – The resolver, the tokens should be in |
---|---|
Returns: | list of tokens with this resolver |
Return type: | list of token objects |
This function is used to retrieve a token list, that can be displayed in the Web UI. It supports pagination. Each retrieved page will also contain a “next” and a “prev”, indicating the next or previous page. If either does not exist, it is None.
Parameters: |
|
---|
Token.serial. If a string like “serial” is provided, we try to convert it to the DB column. :type sortby: A Token column or a string. :param sortdir: Can be “asc” (default) or “desc” :type sortdir: basestring :param psize: The size of the page :type psize: int :param page: The number of the page to view. Starts with 1 ;-) :type page: int :return: dict with tokens, prev, next and count :rtype: dict
get the serial number of a token from a challenge state / transaction
Parameters: | transaction_id (basestring) – the state / transaction id |
---|---|
Returns: | the serial number or None |
Return type: | basestring |
create a new token or update an existing token
Parameters: | param – initialization parameters like: serial (optional) type (optionl, default=hotp) otpkey |
---|
type param: dict :param user: the token owner :type user: User Object :param tokenrealms: the realms, to which the token should belong :type tokenrealms: list
Returns: | token object or None |
---|---|
Return type: | TokenClass object |
Return True if the token is active, otherwise false Returns None, if the token does not exist.
Parameters: | serial (basestring) – The serial number of the token |
---|---|
Returns: | True or False |
Return type: | bool |
Check if the given user is the owner of the token with the given serial number :param serial: The serial number of the token :type serial: str :param user: The user that needs to be checked :type user: User object :return: Return True or False :rtype: bool
This is the workflow to handle a lost token. The token <serial> is lost and will be disabled. A new token of type password token will be created and assigned to the user. The PIN of the lost token will be copied to the new token. The new token will have a certain validity period.
Parameters: |
|
---|
characters, “c”: lower case characters, “n”: digits and “s”: special characters :type contents: A string like “Ccn” :param pw_len: The length of the generated password :type pw_len: int :param options: optional values for the decorator passed from the upper API level :type options: dict
Returns: | result dictionary |
---|
remove the token that matches the serial number or all tokens of the given user and also remove the realm associations and all its challenges
Parameters: |
|
---|---|
Returns: | The number of deleted token |
Return type: | int |
Reset the failcounter :param serial: :param user: :return: The number of tokens, that were resetted :rtype: int
Resyncronize the token of the given serial number by searching the otp1 and otp2 in the future otp values.
Parameters: |
|
---|---|
Returns: |
The auth counters are stored in the token info database field. There are different counters, that can be set
count_auth -> max=False, success=False count_auth_max -> max=True, success=False count_auth_success -> max=False, success=True count_auth_success_max -> max=True, success=True
Parameters: |
|
---|
to be modified :type max: bool :param success: True, if either count_auth_success or count_auth_success_max are to be modified :type success: bool :return: number of modified tokens :rtype: int
The count window is used during authentication to find the matching OTP value. This sets the count window per token.
Parameters: |
|
---|---|
Returns: | number of modified tokens |
Return type: | int |
Set the default values for the token with the given serial number :param serial: token serial :type serial: basestring :return: None
Set the description of a token
Parameters: |
|
---|---|
Returns: | number of modified tokens |
Return type: | int |
Set the hashlib in the tokeninfo. Can be something like sha1, sha256...
Parameters: |
|
---|---|
Returns: | the number of token infos set |
Return type: | int |
Set the maximum fail counts of tokens. This is the maximum number a failed authentication is allowed.
Parameters: |
|
---|---|
Returns: | number of modified tokens |
Return type: | int |
Set the otp length of the token defined by serial or for all tokens of the user. The OTP length is usually 6 or 8.
Parameters: |
|
---|---|
Returns: | number of modified tokens |
Return type: | int |
Set the token PIN of the token. This is the static part that can be used to authenticate.
Parameters: |
|
---|
user will be set :type used: User object :param serial: If the serial is specified, the PIN for this very token will be set. :return: The number of PINs set (usually 1) :rtype: int
Set the SO PIN of a smartcard. The SO Pin can be used to reset the PIN of a smartcard. The SO PIN is stored in the database, so that it could be used for automatic processes for User PIN resetting.
Parameters: |
|
---|---|
Returns: | The number of SO PINs set. (usually 1) |
Return type: | int |
This sets the user pin of a token. This just stores the information of the user pin for (e.g. an eTokenNG, Smartcard) in the database
Parameters: |
|
---|---|
Returns: | The number of PINs set (usually 1) |
Return type: | int |
Set all realms of a token. This sets the realms new. I.e. it does not add realms. So realms that are not contained in the list will not be assigned to the token anymore.
Thus, setting realms=[] clears all realms assignments.
Parameters: |
|
---|---|
Returns: | the number of tokens, to which realms where added. As a serial |
number should be unique, this is either 1 or 0. :rtype: int
The sync window is the window that is used during resync of a token. Such many OTP values are calculated ahead, to find the matching otp value and counter.
Parameters: |
|
---|---|
Returns: | number of modified tokens |
Return type: | int |
returns true if the token with the given serial number exists
Parameters: | serial – the serial number of the token |
---|