Removed keyword arg for advertising token version from encrypt(). Added an encrypt() and decrypt() function to the client which passthrough to the functions in encryption.py. Added an identity_scope parameter to the client's constructor. Refactored tests & examples which create a client to use the client.encrypt() and client.decrypt() passthroughs and to provide the appropriate identity_scope to the client's constructor.

Author: Ian-Nara

examples/sample_auto_refresh.py

@@ -2,7 +2,7 @@
 import sys
 import time
 
-from uid2_client import EncryptionKeysAutoRefresher
+from uid2_client import EncryptionKeysAutoRefresher, IdentityScope
 from uid2_client import Uid2Client
 from uid2_client import decrypt
 
@@ -20,7 +20,7 @@ def _usage():
 secret_key = sys.argv[3]
 ad_token = sys.argv[4]
 
-client = Uid2Client(base_url, auth_key, secret_key)
+client = Uid2Client(base_url, auth_key, secret_key, IdentityScope.UID2)
 with EncryptionKeysAutoRefresher(client, dt.timedelta(seconds=4), dt.timedelta(seconds=7)) as refresher:
     for i in range(0, 20):
         refresh_result = refresher.current_result()

examples/sample_client.py

@@ -22,9 +22,9 @@ def _usage():
 secret_key = sys.argv[3]
 ad_token = sys.argv[4]
 
-client = Uid2Client(base_url, auth_key, secret_key)
+client = Uid2Client(base_url, auth_key, secret_key, IdentityScope.UID2)
 keys = client.refresh_keys()
-decrypt_result = decrypt(ad_token, keys)
+decrypt_result = client.decrypt(ad_token, keys)
 
 print('UID2 =', decrypt_result.uid2)
 print('Established =', decrypt_result.established)
@@ -34,5 +34,5 @@ def _usage():
 # Not required for DSPs, but for those using UID2 sharing functionality this shows how to encrypt a raw UID2 into
 # a new advertising token.
 # IdentityScope could be UID2 or EUID
-new_ad_token = encrypt(decrypt_result.uid2, IdentityScope.UID2, keys)
+new_ad_token = client.encrypt(decrypt_result.uid2, keys)
 print('New Ad Token =', new_ad_token)

examples/sample_encryption.py

@@ -21,7 +21,7 @@ def _usage():
 ad_token = sys.argv[4]
 str_data = sys.argv[5]
 
-client = Uid2Client(base_url, auth_key, secret_key)
+client = Uid2Client(base_url, auth_key, secret_key, IdentityScope.UID2)
 keys = client.refresh_keys()
 
 data = bytes(str_data, 'utf-8')

tests/sharing_test.py

@@ -29,11 +29,11 @@
 
 class TestSharing(unittest.TestCase):
     def setup_sharing_and_encrypt(self, id_scope=IdentityScope.UID2):
-        client = Uid2Client("endpoint", "key", _client_secret)
+        client = Uid2Client("endpoint", "key", _client_secret, id_scope)
         json = self._key_set_to_json_for_sharing([_master_key, _site_key])
         keys = client.refresh_json(json)
 
-        ad_token = encrypt(_example_uid, id_scope, keys)
+        ad_token = client.encrypt(_example_uid, keys)
 
         return ad_token, keys
 
@@ -75,12 +75,12 @@ def test_can_encrypt_and_decrypt_for_sharing(self):
 
     def test_can_decrypt_another_clients_encrypted_token(self):
         ad_token, keys = self.setup_sharing_and_encrypt()
-        receiving_client = Uid2Client("endpoint2", "authkey2", _client_secret)
+        receiving_client = Uid2Client("endpoint2", "authkey2", _client_secret, IdentityScope.UID2)
         keys_json = self._key_set_to_json_for_sharing_with_header('"default_keyset_id": 12345,', 4874, [_master_key, _site_key])
 
         receiving_keys = receiving_client.refresh_json(keys_json)
 
-        result = decrypt(ad_token, receiving_keys)
+        result = receiving_client.decrypt(ad_token, receiving_keys)
         self.assertEqual(_example_uid, result.uid2)
 
     def test_sharing_token_is_v4(self):
@@ -121,51 +121,51 @@ def test_multiple_keys_per_keyset(self):
                             _master_secret, keyset_id=1)
         site_key2 = EncryptionKey(_site_key_id, _site_id, _now - dt.timedelta(days=-2), _now - dt.timedelta(days=-1), _now - dt.timedelta(hours=-1),
                           _site_secret, keyset_id=99999)
-        client = Uid2Client("endpoint", "authkey", _client_secret)
+        client = Uid2Client("endpoint", "authkey", _client_secret, IdentityScope.UID2)
         json_body = self._key_set_to_json_for_sharing([_master_key, master_key2, _site_key, site_key2])
         keys = client.refresh_json(json_body)
 
-        ad_token = encrypt(_example_uid, IdentityScope.UID2, keys)
+        ad_token = client.encrypt(_example_uid, keys)
 
-        result = decrypt(ad_token, keys)
+        result = client.decrypt(ad_token, keys)
 
         self.assertEqual(_example_uid, result.uid2)
 
     def test_cannot_encrypt_if_no_key_from_default_keyset(self):
-        client = Uid2Client("endpoint", "authkey", _client_secret)
+        client = Uid2Client("endpoint", "authkey", _client_secret, IdentityScope.UID2)
         json_body = self._key_set_to_json_for_sharing([_master_key])
         keys = client.refresh_json(json_body)
 
         self.assertRaises(EncryptionError, encrypt, _example_uid, IdentityScope.UID2, keys)
 
     def test_cannot_encrypt_if_theres_no_default_keyset_header(self):
-        client = Uid2Client("endpoint", "authkey", _client_secret)
+        client = Uid2Client("endpoint", "authkey", _client_secret, IdentityScope.UID2)
         json_body = self._key_set_to_json_for_sharing_with_header("", _site_id, [_master_key, _site_key])
         keys = client.refresh_json(json_body)
         self.assertRaises(EncryptionError, encrypt, _example_uid, IdentityScope.UID2, keys)
 
 
     def test_expiry_in_token_matches_expiry_in_reponse(self):
-        client = Uid2Client("endpoint", "authkey", _client_secret)
+        client = Uid2Client("endpoint", "authkey", _client_secret, IdentityScope.UID2)
         json_body = self._key_set_to_json_for_sharing_with_header('"default_keyset_id": 99999, "token_expiry_seconds": 2,', 99999, [_master_key, _site_key])
         keys = client.refresh_json(json_body)
 
         now = dt.datetime.now(tz=timezone.utc)
-        ad_token = encrypt(_example_uid, IdentityScope.UID2, keys)
+        ad_token = client.encrypt(_example_uid, keys)
 
-        result = decrypt(ad_token, keys, now=now + dt.timedelta(seconds=1))
+        result = client.decrypt(ad_token, keys, now=now + dt.timedelta(seconds=1))
         self.assertEqual(_example_uid, result.uid2)
 
         self.assertRaises(EncryptionError, decrypt, ad_token, keys, now=now + dt.timedelta(seconds=3))
 
     def test_encrypt_key_inactive(self):
-        client = Uid2Client("endpoint", "authkey", _client_secret)
+        client = Uid2Client("endpoint", "authkey", _client_secret, IdentityScope.UID2)
         key = EncryptionKey(245, _site_id, _now, _now + dt.timedelta(days=1), _now +dt.timedelta(days=2), _site_secret, keyset_id=99999)
         keys = client.refresh_json(self._key_set_to_json_for_sharing([_master_key, key]))
         self.assertRaises(EncryptionError, encrypt, _example_uid, IdentityScope.UID2, keys)
 
     def test_encrypt_key_expired(self):
-        client = Uid2Client("endpoint", "authkey", _client_secret)
+        client = Uid2Client("endpoint", "authkey", _client_secret, IdentityScope.UID2)
         key = EncryptionKey(245, _site_id, _now, _now, _now - dt.timedelta(days=1), _site_secret, keyset_id=99999)
         keys = client.refresh_json(self._key_set_to_json_for_sharing([_master_key, key]))
         self.assertRaises(EncryptionError, encrypt, _example_uid, IdentityScope.UID2, keys)

tests/test_encryption.py

@@ -340,20 +340,6 @@ def test_decrypt_token_v2_custom_now(self):
         result = decrypt(token, keys, now=expiry - dt.timedelta(seconds=1))
         self.assertEqual(_example_id, result.uid2)
 
-
-    def test_smoke_token_v3(self):
-        uid2 = _example_id
-        identity_scope = IdentityScope.UID2
-        now = dt.datetime.now(tz=timezone.utc)
-
-        keys = EncryptionKeysCollection([_master_key, _site_key, _keyset_key], default_keyset_id=20,
-                                        master_keyset_id=9999, caller_site_id=20)
-
-        result = encrypt(uid2, identity_scope, keys, now=now, ad_token_version=AdvertisingTokenVersion.ADVERTISING_TOKEN_V3)
-        final = decrypt(result, keys, now=now)
-
-        self.assertEqual(uid2, final.uid2)
-
     def test_smoke_token_v4(self):
         uid2 = _example_id
         identity_scope = IdentityScope.UID2

tests/test_key_parse.py

@@ -1,5 +1,5 @@
 import unittest
-from uid2_client import Uid2Client
+from uid2_client import Uid2Client, IdentityScope
 import datetime as dt
 import base64
 
@@ -36,7 +36,7 @@ def test_key_parse(self):
             "}, " + \
             "\"status\": \"success\" }"
 
-        client = Uid2Client("ep", "ak", "ioG3wKxAokmp+rERx6A4kM/13qhyolUXIu14WN16Spo=")
+        client = Uid2Client("ep", "ak", "ioG3wKxAokmp+rERx6A4kM/13qhyolUXIu14WN16Spo=", IdentityScope.UID2)
 
         now = dt.datetime.now(tz=dt.timezone.utc)
 
@@ -65,7 +65,7 @@ def test_key_parse(self):
         self.assertEqual("DD67xF8OFmbJ1/lMPQ6fGRDbJOT4kXErrYWcKdFfCUE=", base64.b64encode(key.secret).decode("ascii"))
 
     def test_parse_key_error(self):
-        client = Uid2Client("ep", "ak", "ioG3wKxAokmp+rERx6A4kM/13qhyolUXIu14WN16Spo=")
+        client = Uid2Client("ep", "ak", "ioG3wKxAokmp+rERx6A4kM/13qhyolUXIu14WN16Spo=", IdentityScope.UID2)
         self.assertRaises(BaseException, client.refresh_json, "{\"status\": \"error\"}")
         self.assertRaises(BaseException, client.refresh_json, "{\"body\": \"error\"}")
         self.assertRaises(BaseException, client.refresh_json, "{\"body\": [1, 2, 3]}")

uid2_client/client.py

@@ -13,8 +13,10 @@
 import urllib.request as request
 import pkg_resources
 
-from .keys import EncryptionKey, EncryptionKeysCollection
+from uid2_client import encryption
 from .encryption import _decrypt_gcm, _encrypt_gcm
+from .keys import EncryptionKey, EncryptionKeysCollection
+from .identity_scope import IdentityScope
 
 
 def _make_dt(timestamp):
@@ -33,12 +35,12 @@ class Uid2Client:
     Examples:
         Connect to the UID2 service and obtain the latest encryption keys:
         >>> from uid2_client import *
-        >>> client = Uid2Client('https://prod.uidapi.com', 'my-authorization-key', 'my-secret-key')
+        >>> client = Uid2Client('https://prod.uidapi.com', 'my-authorization-key', 'my-secret-key', IdentityScope.UID2)
         >>> keys = client.refresh_keys()
         >>> uid2 = decrypt('some-ad-token', keys).uid2
     """
 
-    def __init__(self, base_url, auth_key, secret_key):
+    def __init__(self, base_url, auth_key, secret_key, identity_scope):
         """Create a new Uid2Client client.
 
         Args:
@@ -52,6 +54,7 @@ def __init__(self, base_url, auth_key, secret_key):
         self._base_url = base_url
         self._auth_key = auth_key
         self._secret_key = base64.b64decode(secret_key)
+        self._identity_scope = identity_scope
 
     def refresh_keys(self):
         """Get the latest encryption keys for advertising tokens.
@@ -72,6 +75,37 @@ def refresh_json(self, json_str):
         body = json.loads(json_str)
         return self._parse_keys_json(body['body'])
 
+    def encrypt(self, uid2, keys, keyset_id=None):
+        """ Encrypt an UID2 into a sharing token
+
+            Args:
+                uid2: the UID2 or EUID to be encrypted
+                keys (EncryptionKeysCollection): collection of keys to choose from for encryption
+                keyset_id (int) : An optional keyset id to use for the encryption. Will use default keyset if left blank
+
+            Keyword Args:
+                now (Datetime): the datettime to use for now. Defaults to utc now
+
+            Returns (str): Sharing Token
+            """
+        return encryption.encrypt(uid2, self._identity_scope, keys, keyset_id)
+
+    def decrypt(self, token, keys, now=dt.datetime.now(tz=timezone.utc)):
+        """Decrypt advertising token to extract UID2 details.
+
+            Args:
+                token (str): advertising token to decrypt
+                keys (EncryptionKeysCollection): collection of keys to decrypt the token
+                now (datetime): date/time to use as "now" when doing token expiration check
+
+            Returns:
+                DecryptedToken: details extracted from the advertising token
+
+            Raises:
+                EncryptionError: if token version is not supported, the token has expired,
+                                 or no required decryption keys present in the keys collection
+        """
+        return encryption.decrypt(token, keys, now)
 
     def _parse_keys_json(self, resp_body):
         keys = []

uid2_client/encryption.py

@@ -202,7 +202,6 @@ def encrypt(uid2, identity_scope, keys, keyset_id=None, **kwargs):
 
     Keyword Args:
         now (Datetime): the datettime to use for now. Defaults to utc now
-        ad_token_version (AdvertisingTokenVersion): Defaults to v4
 
     Returns (str): Sharing Token
 
@@ -211,9 +210,7 @@ def encrypt(uid2, identity_scope, keys, keyset_id=None, **kwargs):
     if now is None:
         now = dt.datetime.now(tz=timezone.utc)
 
-    ad_token_version = kwargs.get("ad_token_version")
-    if ad_token_version is None:
-        ad_token_version = AdvertisingTokenVersion.ADVERTISING_TOKEN_V4
+    ad_token_version = AdvertisingTokenVersion.ADVERTISING_TOKEN_V4
 
     key = keys.get_default_keyset_key(now) if keyset_id is None else keys.get_by_keyset_key(keyset_id, now)
     master_key = keys.get_by_keyset_key(keys.get_master_keyset_id(), now)
@@ -249,7 +246,7 @@ def encrypt_data(data, identity_scope, **kwargs):
                                          key from; the key will be selected using site_id
         site_id (int): ID of the site for which the encryption key is to be used;
                        the key will be looked up from the keys collection;
-                       if this is specified, you can't specificy advertising_token
+                       if this is specified, you can't specify advertising_token
         advertising_token (str): token to decrypt in order to obtain the site_id
         now (datetime): date/time to use as "now" for checking whether advertising_token
                         or site encryption key have expired (default: UTC now) as well as