add optional checksum

Author: Fabien Coelho

CacheToolsUtils.py

@@ -374,45 +374,57 @@ 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 hsize: size of hashed key, default is *16*.
+    :param csize: value checksum size, default is *0*.
 
     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.
+    as each value is encrypted with its own key and nonce.
 
     Algorithms:
-    - SHA3: hash/key/nonce derivation.
+    - SHA3: hash/key/nonce derivation and checksum.
     - Salsa20: value encryption.
     """
 
-    def __init__(self, cache: MutableMapping, secret: bytes, hsize: int = 16):
+    def __init__(self, cache: MutableMapping, secret: bytes, hsize: int = 16, csize: int = 0):
         self._cache = cache
         assert len(secret) >= 16
         self._secret = secret
-        assert 8 <= hsize <= 24
+        assert 8 <= hsize <= 32
         self._hsize = hsize
+        assert 0 <= csize <= 32
+        self._csize = csize
         from Crypto.Cipher import Salsa20
         self._cipher = Salsa20
 
-    def _keydev(self, key):
+    def _keydev(self, key) -> tuple[bytes, bytes, bytes]:
+        """Compute hash, key and nonce from initial key."""
         hkey = hashlib.sha3_512(key + self._secret).digest()
-        sz = self._hsize
-        return (hkey[:sz], hkey[sz:sz+32], hkey[sz+32:sz+40])
+        # NOTE hash and nonce may overlap, which is not an issue
+        return (hkey[:self._hsize], hkey[32:], hkey[24:32])
 
     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)
+        xval = self._cipher.new(key=vkey, nonce=vnonce).encrypt(val)
+        if self._csize:
+            cs = hashlib.sha3_256(val).digest()[:self._csize]
+            xval = cs + xval
+        self._cache[hkey] = xval
 
     def __getitem__(self, key):
         hkey, vkey, vnonce = self._keydev(key)
-        return self._cipher.new(key=vkey, nonce=vnonce).decrypt(self._cache[hkey])
+        xval = self._cache[hkey]
+        if self._csize:  # split cs from encrypted value
+            cs, xval = xval[:self._csize], xval[self._csize:]
+        val = self._cipher.new(key=vkey, nonce=vnonce).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):

docs/REFERENCE.md

@@ -91,10 +91,11 @@ Hashing is based on _SHA3_, encryption uses _Salsa20_.
 Because of the stream cipher the value length is somehow leaked.
 
 ```python
-cache = EncryptedCache(actual_cache, secret=b"super secret stuff you cannot guess", hsize=16)
+cache = EncryptedCache(actual_cache, secret=b"super secret stuff you cannot guess", hsize=16, csize=0)
 ```
 
-Hash size $s$ can be extended up to _24_, key collision probability is $2^{-4 s}$.
+Hash size `hsize` can be extended up to _32_, key collision probability is $2^{-4 s}}$.
+An optional value checksum can be triggered by setting `csize`.
 
 The point of this class is to bring security to cached data on distributed
 systems such as Redis.  There is no much point to encrypting in-memory caches.
@@ -117,13 +118,10 @@ def foo(what, ever):
     return …
 ```
 
-## ToBytesCache
+## ToBytesCache and BytesCache
 
-Map keys and values to bytes.
-
-## BytesCache
-
-Handle bytes keys and values and map them to strings.
+Map keys and values to bytes, or
+handle bytes keys and values and map them to strings.
 
 ## MemCached
 

docs/VERSIONS.md

@@ -19,11 +19,12 @@ Install [package](https://pypi.org/project/CacheToolsUtils/) from
   Maybe the existing client can do that with appropriate options?
 - `cached`: add `contains` and `delete` parameters to change names?
 - I cannot say that all this is clear wrt `str` vs `bytes` vs whatever…
-- add integrity check to `EncryptedCache`.
+- allow to change encryption algorithm?
 
 ## ? on ?
 
 Code cleanup.
+Add optional integrity check to `EncryptedCache`.
 
 ## 10.0 on 2024-12-07
 

test.py

@@ -246,7 +246,7 @@ def test_redis():
     c0.flushdb()
 
     c1 = ctu.RedisCache(c0, raw=True)
-    c2 = ctu.EncryptedCache(c1, SECRET, hsize=24)
+    c2 = ctu.EncryptedCache(c1, SECRET, hsize=20, csize=4)
     c3 = ctu.ToBytesCache(c2)
     c4 = ctu.DebugCache(c3, log)
     cache = ctu.LockedCache(c4, threading.RLock())
@@ -563,10 +563,20 @@ def test_cache_key():
 
 def test_encrypted_cache():
     # bytes
-    cache = ctu.EncryptedCache(ctu.DictCache(), SECRET)
+    actual = ctu.DictCache()
+    cache = ctu.EncryptedCache(actual, SECRET, csize=1)
     cache[b"Hello"] = b"World!"
     assert b"Hello" in cache
     assert cache[b"Hello"] == b"World!"
+    # bad checksum
+    assert len(actual) == 1
+    k = list(actual.keys())[0]
+    actual[k] = bytes([(actual[k][0] + 42) % 256]) + actual[k][1:]
+    try:
+        _ = cache[b"Hello"]
+        pytest.fail("must raise an exception")
+    except KeyError as ke:
+        assert "invalid encrypted value" in str(ke)
     del cache[b"Hello"]
     assert b"Hello" not in cache
     # strings