Working OpenPAYGO Token implementation

Author: benmod

README.md

@@ -33,30 +33,29 @@ You can install the library by running `pip install openpaygo` or adding `openpa
 
 You can use the `generate_token()` function to generate an OpenPAYGOToken Token. The function takes the following parameters, and they should match the configuration in the hardware of the device: 
 
-- `secret_key` (required): The secret key of the device
-- `value` (required): The value to be passed in the token (typically the number of days of activation)
-- `count` (required): The token count used to make the last token. 
-- `set_mode` (optional): If set to `true`, the generated token will be a Set Time token, otherwise it is Add Time token. 
+- `secret_key` (required): The secret key of the device. Must be passed as an hexadecimal string (with 32 characters). 
+- `count` (required): The token count used to make the last token.
+- `value` (optional): The value to be passed in the token (typically the number of days of activation). Optional if the `token_type` is Disable PAYG or Counter Sync. The value must be between 0 and 995. 
+- `token_type` (optional): Used to set the type of token (default is Add Time). Token types can be found in the `TokenType` class: ADD_TIME, SET_TIME, DISABLE_PAYG, COUNTER_SYNC. 
 - `starting_code` (optional): If not provided, it is generated according to the method defined in the standard (SipHash-2-4 of the key, transformed to digit by the same method as the token generation).
 - `value_divider` (optional): The dividing factor used for the value. 
 - `restricted_digit_set` (optional): If set to `true`, the the restricted digit set will be used (only digits from 1 to 4). 
 - `extended_token` (optional): If set to `true` then a larger token will be generated, able to contain values up to 999999. This is for special use cases of each device, such as settings change, and is not set in the standard. 
 
-
-The function returns the `token` as a string as well as the `updated_count` as a number. 
+The function returns the `updated_count` as a number as well as the `token` as a string, in that order. The function will raise a `ValueError` if the key is in the wrong format or the value invalid. 
 
 
-**Example:**
+**Example 1 - Add 7 days:**
 
 ```
-from openpaygo.token import generate_token
+from openpaygo.optoken import generate_token
 from myexampleproject import device_getter
 
 # We get a device with the parameters we need from our database, this will be specific to your project
 device = device_getter(serial=1234)
 
 # We get the new token and update the count
-new_token, device.count = generate_token(
+device.count, new_token = generate_token(
   secret_key=device.secret_key,
   value=7,
   count=device.count
@@ -66,4 +65,81 @@ print('Token: '+new_token)
 device.save() # We save the new count that we set for the device
 ```
 
-## Getting Started - Decoding a Token
+**Example 2 - Disable PAYG (unlock forever):**
+
+```
+from openpaygo.optoken import generate_token, TokenType
+
+...
+
+# We get the new token and update the count
+device.count, new_token = generate_token(
+  secret_key=device.secret_key,
+  token_type=TokenType.DISABLE_PAYG,
+  count=device.count
+)
+
+print('Token: '+new_token)
+device.save() # We save the new count that we set for the device
+```
+
+
+## Getting Started - Decoding a Token
+
+You can use the `decode_token()` function to generate an OpenPAYGOToken Token. The function takes the following parameters, and they should match the configuration in the hardware of the device: 
+
+- `token` (required): The token that was given by the user
+- `secret_key` (required): The secret key of the device
+- `count` (required): The token count of the last valid token. When a device is new, this is 1. 
+- `used_counts` (optional): An array of recently used token counts, as returned by the function itself after the last valid token was decoded. This allows for handling unordered token entry. 
+- `starting_code` (optional): If not provided, it is generated according to the method defined in the standard (SipHash-2-4 of the key, transformed to digit by the same method as the token generation).
+- `value_divider` (optional): The dividing factor used for the value. 
+- `restricted_digit_set` (optional): If set to `true`, the the restricted digit set will be used (only digits from 1 to 4). 
+
+
+The function returns the following variable in this order: 
+- `value`: The value associated with the token (if the token is ADD_TIME or SET_TIME). 
+- `token_type`: The type of the token that was provided. Token types can be found in the `TokenType` class: ADD_TIME, SET_TIME, DISABLE_PAYG, COUNTER_SYNC or ALREADY_USED (if the token is valid but already used), INVALID (if the token was invalid). 
+- `updated_count`: The token count of the token, if it was valid. 
+- `updated_used_counts`: The updated array of recently used token, if the token was valid. 
+
+The function will raise a `ValueError` if the key is in the wrong format, but will not raise an error if the token is invalid (as it is a common expected behaviour), to check the validity of the token you must check the return `token_type` and proceed accordingly depending on the type of token. 
+
+
+**Example:**
+
+```
+from openpaygo.optoken import decode_token
+
+# We assume the users enters a token and that the device state is saved in my_device_state
+...
+
+# We decode the token
+value, token_type, updated_count, updated_used_counts = decode_token(
+  token=token_input,
+  secret_key=my_device_state.secret_key,
+  count=my_device_state.count,
+  used_counts=my_device_state.used_counts
+)
+
+# If the token is valid, we update our count in the device state
+if token_type not in [TokenType.ALREADY_USED, TokenType.INVALID]:
+  my_device_state.count = updated_count
+  my_device_state.used_counts = updated_used_counts
+
+# We perform the appropriate behaviour based on the token data
+if token_type == TokenType.ADD_TIME:
+  my_device_state.days_remaining += value
+  print(f'Added {value} days remaining')
+elif token_type == TokenType.SET_TIME:
+  my_device_state.days_remaining = value
+  print(f'Set to {value} days remaining')
+elif token_type == TokenType.DISABLE_PAYG:
+  my_device_state.unlocked_forever = True
+elif token_type == TokenType.COUNTER_SYNC:
+  print('Counter Synced')
+if token_type == TokenType.ALREADY_USED:
+  print('Token was already used')
+elif token_type == TokenType.INVALID:
+  print('Token is invalid')
+```

optoken/__init__.py

@@ -0,0 +1,6 @@
+from .encode_token import OpenPAYGOTokenEncoder
+from .shared import TokenType
+
+
+def generate_token(**kwargs):
+    return OpenPAYGOTokenEncoder.generate_token(**kwargs)

token/decode_token.py optoken/decode_token.pytoken/decode_token.py renamed to optoken/decode_token.py

@@ -1,4 +1,4 @@
-from shared import OpenPAYGOTokenShared
+from shared import OpenPAYGOTokenShared, TokenType
 from shared_extended import OpenPAYGOTokenSharedExtended
 
 
@@ -7,6 +7,34 @@ class OpenPAYGOTokenDecoder(object):
     MAX_TOKEN_JUMP_COUNTER_SYNC = 100
     MAX_UNUSED_OLDER_TOKENS = 8*2
 
+    @classmethod
+    def decode_token(cls, token, secret_key, last_count, used_counts=None, starting_code=None, value_divider=1, restricted_digit_set=False):
+        secret_key = OpenPAYGOTokenShared.load_secret_key_from_hex(secret_key)
+        if not starting_code:
+            # We generate the starting code from the key if not provided
+            starting_code = OpenPAYGOTokenShared.generate_starting_code(secret_key)
+        if not restricted_digit_set:
+            if len(token) <= 9:
+                extended_token = False
+            elif len(token) <= 12:
+                extended_token = True
+            else:
+                raise ValueError("Token is too long")
+        elif restricted_digit_set:
+            if len(token) <= 15:
+                extended_token = False
+            elif len(token) <= 20:
+                extended_token = True
+            else:
+                raise ValueError("Token is too long")
+        if not extended_token:
+            value, token_type, count, updated_counts = cls.get_activation_value_count_and_type_from_token(token, starting_code, secret_key, last_count, restricted_digit_set, used_counts)
+        else:
+            value, token_type, count, updated_counts = cls.get_activation_value_count_from_extended_token(token, starting_code, secret_key, last_count, restricted_digit_set, used_counts)
+        if value and value_divider:
+            value = value / value_divider
+        return value, token_type, count, updated_counts
+
     @classmethod
     def get_activation_value_count_and_type_from_token(cls, token, starting_code, key, last_count,
                                                        restricted_digit_set=False, used_counts=None):
@@ -26,40 +54,48 @@ def get_activation_value_count_and_type_from_token(cls, token, starting_code, ke
         for count in range(0, max_count_try):
             masked_token = OpenPAYGOTokenShared.put_base_in_token(current_code, token_base)
             if count % 2:
-                this_type = OpenPAYGOTokenShared.TOKEN_TYPE_SET_TIME
+                if value == OpenPAYGOTokenShared.COUNTER_SYNC_VALUE:
+                    this_type = TokenType.COUNTER_SYNC
+                elif value == OpenPAYGOTokenShared.PAYG_DISABLE_VALUE:
+                    this_type = TokenType.DISABLE_PAYG
+                else:
+                    this_type = TokenType.SET_TIME
             else:
-                this_type = OpenPAYGOTokenShared.TOKEN_TYPE_ADD_TIME
+                this_type = TokenType.ADD_TIME
             if masked_token == token:
                 if cls._count_is_valid(count, last_count, value, this_type, used_counts):
-                    return value, count, this_type
+                    updated_counts = cls.update_used_counts(used_counts, value, count, this_type)
+                    return value, this_type, count, updated_counts
                 else:
                     valid_older_token = True
             current_code = OpenPAYGOTokenShared.generate_next_token(current_code, key)  # If not we go to the next token
         if valid_older_token:
-            return -2, None, None
-        return None, None, None
+            return None, TokenType.ALREADY_USED, None, None
+        return None, TokenType.INVALID, None, None
 
     @classmethod
     def _count_is_valid(cls, count, last_count, value, type, used_counts):
         if value == OpenPAYGOTokenShared.COUNTER_SYNC_VALUE:
-            if count > last_count - 30:
+            if count > (last_count - cls.MAX_TOKEN_JUMP):
                 return True
         elif count > last_count:
             return True
         elif cls.MAX_UNUSED_OLDER_TOKENS > 0:
             if count > last_count - cls.MAX_UNUSED_OLDER_TOKENS:
-                if count not in used_counts and type == OpenPAYGOTokenShared.TOKEN_TYPE_ADD_TIME:
+                if count not in used_counts and type == TokenType.ADD_TIME:
                     return True
         return False
 
     @classmethod
     def update_used_counts(cls, past_used_counts, value, new_count, type):
+        if not past_used_counts:
+            return None
         highest_count = max(past_used_counts) if past_used_counts else 0
         if new_count > highest_count:
             highest_count = new_count
         bottom_range = highest_count-cls.MAX_UNUSED_OLDER_TOKENS
         used_counts = []
-        if type != OpenPAYGOTokenShared.TOKEN_TYPE_ADD_TIME or value == OpenPAYGOTokenShared.COUNTER_SYNC_VALUE or value == OpenPAYGOTokenShared.PAYG_DISABLE_VALUE:
+        if type != TokenType.ADD_TIME or value == OpenPAYGOTokenShared.COUNTER_SYNC_VALUE or value == OpenPAYGOTokenShared.PAYG_DISABLE_VALUE:
             # If it is not an Add-Time token, we mark all the past tokens as used in the range
             for count in range(bottom_range, highest_count+1):
                 used_counts.append(count)
@@ -80,20 +116,30 @@ def _decode_base(cls, starting_code_base, token_base):
 
     @classmethod
     def get_activation_value_count_from_extended_token(cls, token, starting_code, key, last_count,
-                                                       restricted_digit_set=False):
+                                                       restricted_digit_set=False, used_counts=None):
         if restricted_digit_set:
             token = OpenPAYGOTokenSharedExtended.convert_from_4_digit_token(token)
         token_base = OpenPAYGOTokenSharedExtended.get_token_base(token) # We get the base of the token
         current_code = OpenPAYGOTokenSharedExtended.put_base_in_token(starting_code, token_base) # We put it into the starting code
         starting_code_base = OpenPAYGOTokenSharedExtended.get_token_base(starting_code) # We get the base of the starting code
         value = cls._decode_base_extended(starting_code_base, token_base)  # If there is a match we get the value from the token
-        for count in range(0, 30):
+        max_count_try = last_count + cls.MAX_TOKEN_JUMP + 1
+        for count in range(0, max_count_try):
             masked_token = OpenPAYGOTokenSharedExtended.put_base_in_token(current_code, token_base)
-            if masked_token == token and count > last_count:
-                clean_count = count-1
-                return value, clean_count
+            if count % 2:
+                this_type = TokenType.SET_TIME
+            else:
+                this_type = TokenType.ADD_TIME
+            if masked_token == token:
+                if cls._count_is_valid(count, last_count, value, this_type, used_counts):
+                    updated_counts = cls.update_used_counts(used_counts, value, count, this_type)
+                    return value, this_type, count, updated_counts
+                else:
+                    valid_older_token = True
             current_code = OpenPAYGOTokenSharedExtended.generate_next_token(current_code, key) # If not we go to the next token
-        return None, None, None
+        if valid_older_token:
+            return None, TokenType.ALREADY_USED, None, None
+        return None, TokenType.INVALID, None, None
 
     @classmethod
     def _decode_base_extended(cls, starting_code_base, token_base):

token/encode_token.py optoken/encode_token.pytoken/encode_token.py renamed to optoken/encode_token.py

@@ -1,27 +1,40 @@
-from shared import OpenPAYGOTokenShared
+from shared import OpenPAYGOTokenShared, TokenType
 from shared_extended import OpenPAYGOTokenSharedExtended
 
 
 class OpenPAYGOTokenEncoder(object):
 
     @classmethod
-    def generate_token(cls, secret_key, value, count, set_mode=False, starting_code=None, value_divider=1, restricted_digit_set=False, extended_token=False):
+    def generate_token(cls, secret_key, count, value=None, token_type=TokenType.ADD_TIME, starting_code=None, value_divider=1, restricted_digit_set=False, extended_token=False):
+        secret_key = OpenPAYGOTokenShared.load_secret_key_from_hex(secret_key)
         if not starting_code:
             # We generate the starting code from the key if not provided
-            starting_code = cls.generate_starting_code(secret_key)
-        if set_mode:
-            mode = OpenPAYGOTokenShared.TOKEN_TYPE_SET_TIME
+            starting_code = OpenPAYGOTokenShared.generate_starting_code(secret_key)
+        if token_type in [TokenType.ADD_TIME, TokenType.SET_TIME]:
+            value = int(round(value * value_divider, 0))
+            if not extended_token:
+                max_value = OpenPAYGOTokenShared.MAX_ACTIVATION_VALUE
+            else:
+                max_value = OpenPAYGOTokenSharedExtended.MAX_ACTIVATION_VALUE
+            if value > max_value:
+                raise ValueError('The value provided is too high.')
+        elif value:
+            raise ValueError('A value is not allowed for this token type.')
         else:
-            mode = OpenPAYGOTokenShared.TOKEN_TYPE_ADD_TIME
-        value = int(round(value / value_divider))
+            if token_type == TokenType.DISABLE_PAYG:
+                value = OpenPAYGOTokenShared.PAYG_DISABLE_VALUE
+            elif token_type == TokenType.COUNTER_SYNC:
+                value = OpenPAYGOTokenShared.COUNTER_SYNC_VALUE
+            else:
+                raise ValueError('The token type provided is not supported.')
         if extended_token:
-            return cls.generate_extended_token(starting_code, secret_key, value, count, mode, restricted_digit_set)
+            return cls.generate_extended_token(starting_code, secret_key, value, count, token_type, restricted_digit_set)
         else:
-            return cls.generate_standard_token(starting_code, secret_key, value, count, mode, restricted_digit_set)
+            return cls.generate_standard_token(starting_code, secret_key, value, count, token_type, restricted_digit_set)
 
     @classmethod
     def generate_standard_token(cls, starting_code=None, key=None, value=None, count=None,
-                                mode=OpenPAYGOTokenShared.TOKEN_TYPE_SET_TIME, restricted_digit_set=False):
+                                mode=TokenType.ADD_TIME, restricted_digit_set=False):
         # We get the first 3 digits with encoded value
         starting_code_base = OpenPAYGOTokenShared.get_token_base(starting_code)
         token_base = cls._encode_base(starting_code_base, value)
@@ -45,7 +58,7 @@ def _encode_base(cls, base, number):
             return number + base
 
     @classmethod
-    def generate_extended_token(cls, starting_code, key, value, count, mode=OpenPAYGOTokenShared.TOKEN_TYPE_SET_TIME, restricted_digit_set=False):
+    def generate_extended_token(cls, starting_code, key, value, count, mode=TokenType.ADD_TIME, restricted_digit_set=False):
         starting_code_base = OpenPAYGOTokenSharedExtended.get_token_base(starting_code)
         token_base = cls._encode_base_extended(starting_code_base, value)
         current_token = OpenPAYGOTokenSharedExtended.put_base_in_token(starting_code, token_base)
@@ -59,12 +72,6 @@ def generate_extended_token(cls, starting_code, key, value, count, mode=OpenPAYG
         else:
             final_token = '{:012d}'.format(final_token)
         return new_count, final_token
-    
-    @classmethod
-    def generate_starting_code(cls, key):
-        # We make a hash of the key
-        starting_hash = OpenPAYGOTokenShared.generate_hash(key, key)
-        return OpenPAYGOTokenShared.convert_hash_to_token(starting_hash)
 
     @classmethod
     def _encode_base_extended(cls, base, number):
@@ -76,8 +83,8 @@ def _encode_base_extended(cls, base, number):
     @classmethod
     def _get_new_count(cls, count, mode):
         current_count_odd = count % 2
-        if mode == OpenPAYGOTokenShared.TOKEN_TYPE_SET_TIME:
-            if current_count_odd: # Odd numbers are for Set Time
+        if mode in [TokenType.SET_TIME, TokenType.DISABLE_PAYG, TokenType.COUNTER_SYNC]:
+            if current_count_odd: # Odd numbers are for Set Time, Disable PAYG or Counter Sync
                 new_count = count+2
             else:
                 new_count = count+1

token/shared.py optoken/shared.pytoken/shared.py renamed to optoken/shared.py

@@ -1,5 +1,15 @@
 import siphash
 import struct
+import codecs
+
+
+class TokenType(object):
+    ADD_TIME = 1
+    SET_TIME = 2
+    DISABLE_PAYG = 3
+    COUNTER_SYNC = 4
+    INVALID = 10
+    ALREADY_USED = 11
 
 
 class OpenPAYGOTokenShared(object):
@@ -8,8 +18,6 @@ class OpenPAYGOTokenShared(object):
     PAYG_DISABLE_VALUE = 998
     COUNTER_SYNC_VALUE = 999
     TOKEN_VALUE_OFFSET = 1000
-    TOKEN_TYPE_SET_TIME = 1
-    TOKEN_TYPE_ADD_TIME = 2
 
     @classmethod
     def get_token_base(cls, code):
@@ -37,6 +45,19 @@ def convert_hash_to_token(cls, this_hash):
         result_hash = hi_hash ^ lo_hash # We XOR the two together to get a single 32bits INT
         token = cls._convert_to_29_5_bits(result_hash) # We convert the 32bits value to an INT no greater than 9 digits
         return token
+    
+    @classmethod
+    def generate_starting_code(cls, key):
+        # We make a hash of the key
+        starting_hash = OpenPAYGOTokenShared.generate_hash(key, key)
+        return OpenPAYGOTokenShared.convert_hash_to_token(starting_hash)
+    
+    @classmethod
+    def load_secret_key_from_hex(cls, secret_key):
+        try:
+            return codecs.decode(secret_key, 'hex')
+        except Exception as e:
+            raise ValueError('The secret key provided is not correctly formatted, it should be 32 hexadecimal characters. ')
 
     @classmethod
     def _convert_to_29_5_bits(cls, source):