CacheToolsUtils 10.0__tar.gz → 10.2__tar.gz

{cachetoolsutils-10.0 → cachetoolsutils-10.2}/CacheToolsUtils.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: CacheToolsUtils
-Version: 10.0
+Version: 10.2
 Summary: Cachetools Utilities
 Author-email: Fabien Coelho <cachetools.utils@coelho.net>
 License: CC0
@@ -89,6 +89,7 @@ with `cachetools`.
 - `DebugCache` to trace cache calls using `logging`.
 - `EncryptedCache` a cache with key hashing and value encryption.
 - `ToBytesCache` map keys and values to bytes.
+- `BytesCache` map bytes keys and values to strings.
 
 ### Cache utilities
 

{cachetoolsutils-10.0 → cachetoolsutils-10.2}/CacheToolsUtils.py

@@ -367,6 +367,147 @@ class TwoLevelCache(_MutMapMix, MutableMapping):
         self._cache2.reset()  # type: ignore
 
 
+# NOTE this is quite costly, a Cipher object is created to encrypt/decrypt each value.
+# another design could keep a persistant cipher.
+class _Cipher:
+    """Not so convincing internal class to abstract cipher algorithms."""
+
+    def __init__(self, name):
+        self._name = name
+        if name == "Salsa20":
+            from Crypto.Cipher import Salsa20 as cipher
+            # NOTE hash and nonce may overlap, which is not an issue
+            params = {"key": (32, 64), "nonce": (24, 32)}
+            kwargs = {}
+            size = 0
+        elif name == "ChaCha20":
+            from Crypto.Cipher import ChaCha20 as cipher
+            # NOTE hash and nonce may overlap, which is not an issue
+            params = {"key": (32, 64), "nonce": (24, 32)}
+            kwargs = {}
+            size = 0
+        elif name in ("AES", "AES-128", "AES-128-CBC"):
+            from Crypto.Cipher import AES as cipher
+            params = {"key": (48, 64), "iv": (32, 48)}
+            kwargs = {"mode": cipher.MODE_CBC}
+            size = 16
+        else:
+            raise Exception(f"unexpected cipher: {name}")
+        self._cipher = cipher
+        self._params = params
+        self._kwargs = kwargs
+        if size:
+            from Crypto.Util.Padding import pad, unpad
+            self._pad = lambda s: pad(s, size)
+            self._unpad = lambda s: unpad(s, size)
+        else:
+            self._pad = lambda s: s
+            self._unpad = lambda s: s
+
+    def new(self, derived: bytes):
+        kwargs = {k: derived[v[0]: v[1]] for k, v in self._params.items()}
+        return self._cipher.new(**kwargs, **self._kwargs)  # type: ignore
+
+
+#
+# Encrypted Cache
+#
+class EncryptedCache(_KeyMutMapMix, _StatsMix, MutableMapping):
+    """Encrypted Bytes Key-Value Cache.
+
+    :param secret: bytes of secret, at least 16 bytes.
+    :param hsize: size of hashed key, default is *16*.
+    :param csize: value checksum size, default is *0*.
+    :param cipher: chose cipher from "Salsa20", "AES-128-CBC" or "ChaCha20".
+
+    The key is *not* encrypted but simply hashed, thus they are
+    fixed size with a very low collision probability.
+
+    By design, the clear-text key is needed to recover the value,
+    as each value is encrypted with its own key and nonce.
+
+    Algorithms:
+
+    - SHA3: hash/key/nonce derivation and checksum.
+    - Salsa20, AES-128-CBC or ChaCha20: value encryption.
+    """
+
+    def __init__(self, cache: MutableMapping, secret: bytes, hsize: int = 16, csize: int = 0, cipher: str = "Salsa20"):
+        self._cache = cache
+        assert len(secret) >= 16
+        self._secret = secret
+        assert 8 <= hsize <= 32
+        self._hsize = hsize
+        assert 0 <= csize <= 32
+        self._csize = csize
+        self._cipher = _Cipher(cipher)
+
+    def _derive(self, key) -> tuple[bytes, bytes]:
+        """Derive hash and stuff from initial key and secret."""
+        derived = hashlib.sha3_512(key + self._secret).digest()
+        return (derived[:self._hsize], derived)
+
+    def _key(self, key):
+        return self._derive(key)[0]
+
+    def __setitem__(self, key, val):
+        hkey, derived = self._derive(key)
+        xval = self._cipher.new(derived).encrypt(self._cipher._pad(val))
+        if self._csize:
+            xval = hashlib.sha3_256(val).digest()[:self._csize] + xval
+        self._cache[hkey] = xval
+
+    def __getitem__(self, key):
+        hkey, derived = self._derive(key)
+        xval = self._cache[hkey]
+        if self._csize:  # split cs from encrypted value
+            cs, xval = xval[:self._csize], xval[self._csize:]
+        else:
+            cs = None
+        val = self._cipher._unpad(self._cipher.new(derived).decrypt(xval))
+        if self._csize and cs != hashlib.sha3_256(val).digest()[:self._csize]:
+            raise KeyError(f"invalid encrypted value for key {key}")
+        return val
+
+
+class BytesCache(_KeyMutMapMix, _StatsMix, MutableMapping):
+    """Map bytes to strings."""
+
+    def __init__(self, cache):
+        self._cache = cache
+
+    def _key(self, key):
+        # assert isinstance(key, bytes)
+        return base64.b85encode(key).decode("ASCII")
+
+    def __setitem__(self, key, val):
+        self._cache.__setitem__(self._key(key), self._key(val))
+
+    def __getitem__(self, key):
+        val = self._cache.__getitem__(self._key(key))
+        # assert isinstance(val, str)
+        return base64.b85decode(val)
+
+
+class ToBytesCache(_KeyMutMapMix, _StatsMix, MutableMapping):
+    """Map (JSON-serializable) cache keys and values to bytes."""
+
+    def __init__(self, cache):
+        self._cache = cache
+
+    def _key(self, key):
+        return json.dumps(key, sort_keys=True, separators=(",", ":")).encode("UTF-8")
+
+    def __setitem__(self, key, val):
+        self._cache.__setitem__(self._key(key), self._key(val))
+
+    def __getitem__(self, key):
+        return json.loads(self._cache.__getitem__(self._key(key)).decode("UTF-8"))
+
+
+#
+# CACHED DECORATOR AND HELPERS
+#
 def cached(cache, *args, **kwargs):
     """Extended decorator with delete and exists.
 
@@ -497,7 +638,9 @@ class _HashJsonKey:
         return self._key
 
 
+# NOTE not very useful, behaves as _HashJsonKey.
 def hash_json_key(*args, **kwargs):
+    """Function handling of above class, to keep it hidden."""
     return _HashJsonKey(*args, **kwargs)
 
 
@@ -508,93 +651,9 @@ def full_hash_key(*args, **kwargs) -> str:
     return base64.b85encode(hkey).decode("ASCII")
 
 
-#
-# Encrypted Cache
-#
-class EncryptedCache(_KeyMutMapMix, _StatsMix, MutableMapping):
-    """Encrypted Bytes Key-Value Cache.
-
-    :param secret: bytes of secret, at least 16 bytes.
-    :param hsize: size of hashed key, default is 16.
-
-    The key is *not* encrypted but simply hashed, thus they are
-    fixed size with a very low collision probability.
-
-    By design, the clear-text key is needed to recover the value,
-    as each value is encrypted with its own key.
-
-    There is no integrity check on the value.
-
-    Algorithms:
-    - SHA3: hash/key/nonce derivation.
-    - Salsa20: value encryption.
-    """
-
-    def __init__(self, cache: MutableMapping, secret: bytes, hsize: int = 16):
-        self._cache = cache
-        assert len(secret) >= 16
-        self._secret = secret
-        assert 8 <= hsize <= 24
-        self._hsize = hsize
-        from Crypto.Cipher import Salsa20
-        self._cipher = Salsa20
-
-    def _keydev(self, key):
-        hkey = hashlib.sha3_512(key + self._secret).digest()
-        sz = self._hsize
-        return (hkey[:sz], hkey[sz:sz+32], hkey[sz+32:sz+40])
-
-    def _key(self, key):
-        return self._keydev(key)[0]
-
-    def __setitem__(self, key, val):
-        hkey, vkey, vnonce = self._keydev(key)
-        self._cache[hkey] = self._cipher.new(key=vkey, nonce=vnonce).encrypt(val)
-
-    def __getitem__(self, key):
-        hkey, vkey, vnonce = self._keydev(key)
-        return self._cipher.new(key=vkey, nonce=vnonce).decrypt(self._cache[hkey])
-
-
-class BytesCache(_KeyMutMapMix, _StatsMix, MutableMapping):
-    """Map bytes to strings."""
-
-    def __init__(self, cache):
-        self._cache = cache
-
-    def _key(self, key):
-        # assert isinstance(key, bytes)
-        return base64.b85encode(key).decode("ASCII")
-
-    def __setitem__(self, key, val):
-        self._cache.__setitem__(self._key(key), self._key(val))
-
-    def __getitem__(self, key):
-        val = self._cache.__getitem__(self._key(key))
-        # assert isinstance(val, str)
-        return base64.b85decode(val)
-
-
-class ToBytesCache(_KeyMutMapMix, _StatsMix, MutableMapping):
-    """Map (JSON-serializable) cache keys and values to bytes."""
-
-    def __init__(self, cache):
-        self._cache = cache
-
-    def _key(self, key):
-        return json.dumps(key, sort_keys=True, separators=(",", ":")).encode("UTF-8")
-
-    def __setitem__(self, key, val):
-        self._cache.__setitem__(self._key(key), self._key(val))
-
-    def __getitem__(self, key):
-        return json.loads(self._cache.__getitem__(self._key(key)).decode("UTF-8"))
-
-
 #
 # MEMCACHED
 #
-# FIXME what about bytes?
 class JsonSerde:
     """JSON serialize/deserialize class for MemCached (``pymemcache``).
 
@@ -607,23 +666,23 @@ class JsonSerde:
 
     # keep strings, else json
     def serialize(self, key, value):
-        if isinstance(value, str):
-            return value.encode("utf-8"), 1
-        elif isinstance(value, bytes):
-            return value, 3
+        if isinstance(value, bytes):
+            return value, 1
+        elif isinstance(value, str):
+            return value.encode("utf-8"), 2
         else:
-            return json.dumps(value, sort_keys=True, separators=(",", ":")).encode("utf-8"), 2
+            return json.dumps(value, sort_keys=True, separators=(",", ":")).encode("utf-8"), 3
 
     # reverse previous serialization
     def deserialize(self, key, value, flag):
         if flag == 1:
-            return value.decode("utf-8")
+            return value
         elif flag == 2:
-            return json.loads(value.decode("utf-8"))
+            return value.decode("utf-8")
         elif flag == 3:
-            return value
+            return json.loads(value.decode("utf-8"))
         else:
-            raise Exception("Unknown serialization format")
+            raise Exception(f"Unknown serialization format: {flag}")
 
 
 class MemCached(_KeyMutMapMix, MutableMapping):
@@ -650,8 +709,6 @@ class MemCached(_KeyMutMapMix, MutableMapping):
     # short (250 bytes) ASCII without control chars nor spaces
     # we do not use hashing which might be costly or induce collisions
     def _key(self, key):
-        import base64
-
         return base64.b85encode(str(key).encode("utf-8"))
 
     def __len__(self):
@@ -690,8 +747,6 @@ class PrefixedMemCached(MemCached):
         self._prefix = bytes(prefix, "utf-8")
 
     def _key(self, key):
-        import base64
-
         return self._prefix + base64.b85encode(str(key).encode("utf-8"))
 
 

{cachetoolsutils-10.0 → cachetoolsutils-10.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: CacheToolsUtils
-Version: 10.0
+Version: 10.2
 Summary: Cachetools Utilities
 Author-email: Fabien Coelho <cachetools.utils@coelho.net>
 License: CC0
@@ -89,6 +89,7 @@ with `cachetools`.
 - `DebugCache` to trace cache calls using `logging`.
 - `EncryptedCache` a cache with key hashing and value encryption.
 - `ToBytesCache` map keys and values to bytes.
+- `BytesCache` map bytes keys and values to strings.
 
 ### Cache utilities
 

{cachetoolsutils-10.0 → cachetoolsutils-10.2}/README.md

@@ -43,6 +43,7 @@ with `cachetools`.
 - `DebugCache` to trace cache calls using `logging`.
 - `EncryptedCache` a cache with key hashing and value encryption.
 - `ToBytesCache` map keys and values to bytes.
+- `BytesCache` map bytes keys and values to strings.
 
 ### Cache utilities
 

{cachetoolsutils-10.0 → cachetoolsutils-10.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "CacheToolsUtils"
-version = "10.0"
+version = "10.2"
 authors = [ { name = "Fabien Coelho", email = "cachetools.utils@coelho.net" } ]
 description = "Cachetools Utilities"
 readme = "README.md"