linotp.lib.pairing module

class linotp.lib.pairing.PairingResponse(token_type, pairing_data)

Bases: tuple

property pairing_data

Alias for field number 1

property token_type

Alias for field number 0

linotp.lib.pairing.decrypt_pairing_response(enc_pairing_response)

Parses and decrypts a pairing response into a named tuple PairingResponse consisting of

  • user_public_key - the user’s public key

  • user_token_id - an id for the client to uniquely identify the token.

    this id is necessary, because the client could communicate with more than one linotp, so serials could overlap.

  • serial - the serial identifying the token in linotp

  • user_login - the user login name

It is possible that either user_login or serial is None. Both being None is a valid response according to this function but will be considered an error in the calling method.

The following parameters are needed:

Parameters

enc_pairing_response – The urlsafe-base64 encoded string received from the client

The following exceptions can be raised:

Raises

  • ParameterError – If the pairing response has an invalid format

  • ValueError – If the pairing response has a different version than this implementation (currently hardcoded)

  • ValueError – If the pairing response indicates a different token type than QRToken (also hardcoded)

  • ValueError – If the pairing response field “partition” is not identical to the field “token_type” (“partition” is currently used for the token type id. It is reserved for multiple key usage in a future implementation.)

  • ValueError – If the MAC of the response didn’t match

Returns

Parsed/decrypted PairingReponse

linotp.lib.pairing.generate_pairing_url(token_type, partition=None, serial=None, callback_url=None, callback_sms_number=None, otp_pin_length=None, hash_algorithm=None, use_cert=False)

Generates a pairing url that should be sent to the client.

Mandatory parameters:

Param

token_type The token type for which this url is generated as a string (currently supported is only ‘qr’)

Optional parameters:

Parameters

  • partition – A partition id that should be used during pairing. Partitions identitify a subspace of tokens, that share a common key pair. This currently defaults to the enum id of the token type when set to None and is reserved for future use.

  • serial – When a token for the client was already enrolled (e.g. manually in the manage interface) its serial has to be sent to the client. When serial is not specified the client will receive a so-called ‘anonymous pairing url’ with no token data inside it. The token will then be created after the server received a pairing response from the client.

  • callback_url – A callback URL that should be used by the client to sent back the pairing reponse. Please note, that this url will be cached by the client and used in the challenge step, if the challenge doesn’t provide a custom url

  • callback_sms_number – A sms number that can be used by the client to send back the pairing response. Typically this is used as a fallback for offline pairing. As with the callback url please note, that the number will be cached by the client. If you want a different number in the challenge step you have to send it inside the challenge as specified in the challenge protocol

  • otp_pin_length – The number of digits the otp has to consist of.

  • hash_algorithm – A string value that signifies the hash algorithm used in calculating the hmac. Currently the values ‘sha1’, ‘sha256’, ‘sha512’ are supported. If the parameter is left out the default depends on the token type. qrtoken uses sha256 as default, while hotp/totp uses sha1.

  • use_cert – A boolean, if a server certificate should be used in the pairing url

The function can raise several exceptions:

Raises
Returns

Pairing URL string

linotp.lib.pairing.get_pairing_data_parser(token_type)

fetches a parser for the decrypted inner layer of a pairing response according to its token type.

Parameters

token_type – the token type obtained from the decrypted inner layer

Returns

parser function