cyphera 0.0.1a3__tar.gz

cyphera-0.0.1a3/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: cyphera
+Version: 0.0.1a3
+Summary: Data protection SDK — format-preserving encryption (FF1/FF3), AES-GCM, data masking, and hashing.
+Author-email: Leslie Gutschow <leslie.gutschow@horizondigital.dev>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://cyphera.io
+Project-URL: Repository, https://github.com/cyphera-labs/cyphera-python
+Project-URL: Issues, https://github.com/cyphera-labs/cyphera-python/issues
+Keywords: encryption,fpe,format-preserving,data-protection,masking
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.9
+Requires-Dist: cryptography>=41.0

cyphera-0.0.1a3/README.md

@@ -0,0 +1,23 @@
+# cyphera
+
+Data obfuscation SDK for Python. FPE, AES, masking, hashing.
+
+```
+pip install cyphera
+```
+
+```python
+from cyphera import FF1
+
+cipher = FF1(key, tweak)
+encrypted = cipher.encrypt("0123456789")
+decrypted = cipher.decrypt(encrypted)
+```
+
+## Status
+
+Early development. FF1 and FF3 engines with all NIST test vectors.
+
+## License
+
+Apache 2.0

cyphera-0.0.1a3/cyphera/__init__.py

@@ -0,0 +1,5 @@
+from cyphera.ff1 import FF1
+from cyphera.ff3 import FF3
+
+__all__ = ["FF1", "FF3"]
+__version__ = "0.1.0"

cyphera-0.0.1a3/cyphera/ff1.py

@@ -0,0 +1,142 @@
+"""FF1 Format-Preserving Encryption (NIST SP 800-38G)."""
+
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+import math
+
+DIGITS = "0123456789"
+ALPHANUMERIC = "0123456789abcdefghijklmnopqrstuvwxyz"
+
+
+class FF1:
+    def __init__(self, key: bytes, tweak: bytes, alphabet: str = ALPHANUMERIC):
+        if len(key) not in (16, 24, 32):
+            raise ValueError(f"Key must be 16, 24, or 32 bytes, got {len(key)}")
+        if len(alphabet) < 2:
+            raise ValueError("Alphabet must have >= 2 characters")
+        self._key = key
+        self._tweak = tweak
+        self._alphabet = alphabet
+        self._radix = len(alphabet)
+        self._char_to_int = {c: i for i, c in enumerate(alphabet)}
+
+    def encrypt(self, plaintext: str) -> str:
+        digits = self._to_digits(plaintext)
+        result = self._ff1_encrypt(digits, self._tweak)
+        return self._from_digits(result)
+
+    def decrypt(self, ciphertext: str) -> str:
+        digits = self._to_digits(ciphertext)
+        result = self._ff1_decrypt(digits, self._tweak)
+        return self._from_digits(result)
+
+    def _to_digits(self, s: str) -> list[int]:
+        return [self._char_to_int[c] for c in s]
+
+    def _from_digits(self, d: list[int]) -> str:
+        return "".join(self._alphabet[i] for i in d)
+
+    def _aes_ecb(self, block: bytes) -> bytes:
+        cipher = Cipher(algorithms.AES(self._key), modes.ECB())
+        enc = cipher.encryptor()
+        return enc.update(block) + enc.finalize()
+
+    def _prf(self, data: bytes) -> bytes:
+        y = b"\x00" * 16
+        for i in range(0, len(data), 16):
+            block = bytes(a ^ b for a, b in zip(y, data[i : i + 16]))
+            y = self._aes_ecb(block)
+        return y
+
+    def _expand_s(self, r: bytes, d: int) -> bytes:
+        blocks = (d + 15) // 16
+        out = bytearray(r)
+        for j in range(1, blocks):
+            x = j.to_bytes(16, "big")
+            # XOR with R (not previous block) per NIST SP 800-38G
+            x = bytes(a ^ b for a, b in zip(x, r))
+            enc = self._aes_ecb(x)
+            out.extend(enc)
+        return bytes(out[:d])
+
+    def _num(self, digits: list[int]) -> int:
+        result = 0
+        for d in digits:
+            result = result * self._radix + d
+        return result
+
+    def _str(self, num: int, length: int) -> list[int]:
+        result = [0] * length
+        for i in range(length - 1, -1, -1):
+            result[i] = num % self._radix
+            num //= self._radix
+        return result
+
+    def _compute_b(self, v: int) -> int:
+        return math.ceil(math.ceil(v * math.log2(self._radix)) / 8)
+
+    def _build_p(self, u: int, n: int, t: int) -> bytes:
+        return bytes(
+            [1, 2, 1, (self._radix >> 16) & 0xFF, (self._radix >> 8) & 0xFF, self._radix & 0xFF, 10, u]
+            + list(n.to_bytes(4, "big"))
+            + list(t.to_bytes(4, "big"))
+        )
+
+    def _build_q(self, T: bytes, i: int, num_bytes: bytes, b: int) -> bytes:
+        pad = (16 - ((len(T) + 1 + b) % 16)) % 16
+        q = bytearray(T)
+        q.extend(b"\x00" * pad)
+        q.append(i)
+        if len(num_bytes) < b:
+            q.extend(b"\x00" * (b - len(num_bytes)))
+        start = max(0, len(num_bytes) - b)
+        q.extend(num_bytes[start:])
+        return bytes(q)
+
+    def _ff1_encrypt(self, pt: list[int], T: bytes) -> list[int]:
+        n = len(pt)
+        u, v = n // 2, n - n // 2
+        A, B = pt[:u], pt[u:]
+
+        b = self._compute_b(v)
+        d = 4 * ((b + 3) // 4) + 4
+        P = self._build_p(u, n, len(T))
+
+        for i in range(10):
+            num_b = self._num(B).to_bytes(max(b, 1), "big")
+            if len(num_b) > b:
+                num_b = num_b[-b:] if b > 0 else b""
+            Q = self._build_q(T, i, num_b, b)
+            R = self._prf(P + Q)
+            S = self._expand_s(R, d)
+            y = int.from_bytes(S, "big")
+
+            m = u if i % 2 == 0 else v
+            c = (self._num(A) + y) % (self._radix ** m)
+            A, B = B, self._str(c, m)
+
+        return A + B
+
+    def _ff1_decrypt(self, ct: list[int], T: bytes) -> list[int]:
+        n = len(ct)
+        u, v = n // 2, n - n // 2
+        A, B = ct[:u], ct[u:]
+
+        b = self._compute_b(v)
+        d = 4 * ((b + 3) // 4) + 4
+        P = self._build_p(u, n, len(T))
+
+        for i in range(9, -1, -1):
+            num_a = self._num(A).to_bytes(max(b, 1), "big")
+            if len(num_a) > b:
+                num_a = num_a[-b:] if b > 0 else b""
+            Q = self._build_q(T, i, num_a, b)
+            R = self._prf(P + Q)
+            S = self._expand_s(R, d)
+            y = int.from_bytes(S, "big")
+
+            m = u if i % 2 == 0 else v
+            mod = self._radix ** m
+            c = (self._num(B) - y) % mod
+            B, A = A, self._str(c, m)
+
+        return A + B

cyphera-0.0.1a3/cyphera/ff3.py

@@ -0,0 +1,127 @@
+"""FF3-1 Format-Preserving Encryption (NIST SP 800-38G Rev 1)."""
+
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+
+DIGITS = "0123456789"
+ALPHANUMERIC = "0123456789abcdefghijklmnopqrstuvwxyz"
+
+
+class FF3:
+    def __init__(self, key: bytes, tweak: bytes, alphabet: str = ALPHANUMERIC):
+        if len(key) not in (16, 24, 32):
+            raise ValueError(f"Key must be 16, 24, or 32 bytes, got {len(key)}")
+        if len(tweak) != 8:
+            raise ValueError(f"Tweak must be exactly 8 bytes, got {len(tweak)}")
+        if len(alphabet) < 2:
+            raise ValueError("Alphabet must have >= 2 characters")
+        # FF3 reverses the key
+        self._key = key[::-1]
+        self._tweak = tweak
+        self._alphabet = alphabet
+        self._radix = len(alphabet)
+        self._char_to_int = {c: i for i, c in enumerate(alphabet)}
+
+    def encrypt(self, plaintext: str) -> str:
+        digits = self._to_digits(plaintext)
+        result = self._ff3_encrypt(digits)
+        return self._from_digits(result)
+
+    def decrypt(self, ciphertext: str) -> str:
+        digits = self._to_digits(ciphertext)
+        result = self._ff3_decrypt(digits)
+        return self._from_digits(result)
+
+    def _to_digits(self, s: str) -> list[int]:
+        return [self._char_to_int[c] for c in s]
+
+    def _from_digits(self, d: list[int]) -> str:
+        return "".join(self._alphabet[i] for i in d)
+
+    def _aes_ecb(self, block: bytes) -> bytes:
+        cipher = Cipher(algorithms.AES(self._key), modes.ECB())
+        enc = cipher.encryptor()
+        return enc.update(block) + enc.finalize()
+
+    def _num(self, digits: list[int]) -> int:
+        result = 0
+        for d in digits:
+            result = result * self._radix + d
+        return result
+
+    def _str(self, num: int, length: int) -> list[int]:
+        result = [0] * length
+        for i in range(length - 1, -1, -1):
+            result[i] = num % self._radix
+            num //= self._radix
+        return result
+
+    def _calc_p(self, round_num: int, w: bytes, half: list[int]) -> int:
+        inp = bytearray(16)
+        inp[0:4] = w
+        inp[3] ^= round_num
+
+        rev_half = list(reversed(half))
+        half_num = self._num(rev_half)
+        half_bytes = half_num.to_bytes(max(1, (half_num.bit_length() + 7) // 8), "big") if half_num > 0 else b"\x00"
+
+        if len(half_bytes) <= 12:
+            inp[16 - len(half_bytes) : 16] = half_bytes
+        else:
+            inp[4:16] = half_bytes[-12:]
+
+        rev_inp = bytes(reversed(inp))
+        aes_out = self._aes_ecb(rev_inp)
+        rev_out = bytes(reversed(aes_out))
+        return int.from_bytes(rev_out, "big")
+
+    def _ff3_encrypt(self, pt: list[int]) -> list[int]:
+        n = len(pt)
+        u = (n + 1) // 2
+        v = n - u
+        A, B = pt[:u], pt[u:]
+
+        for i in range(8):
+            if i % 2 == 0:
+                w = self._tweak[4:8]
+                p = self._calc_p(i, w, B)
+                m = self._radix ** u
+                a_num = self._num(list(reversed(A)))
+                y = (a_num + p) % m
+                new = self._str(y, u)
+                A = list(reversed(new))
+            else:
+                w = self._tweak[0:4]
+                p = self._calc_p(i, w, A)
+                m = self._radix ** v
+                b_num = self._num(list(reversed(B)))
+                y = (b_num + p) % m
+                new = self._str(y, v)
+                B = list(reversed(new))
+
+        return A + B
+
+    def _ff3_decrypt(self, ct: list[int]) -> list[int]:
+        n = len(ct)
+        u = (n + 1) // 2
+        v = n - u
+        A, B = ct[:u], ct[u:]
+
+        for i in range(7, -1, -1):
+            if i % 2 == 0:
+                w = self._tweak[4:8]
+                p = self._calc_p(i, w, B)
+                m = self._radix ** u
+                a_num = self._num(list(reversed(A)))
+                y = (a_num - p) % m
+                new = self._str(y, u)
+                A = list(reversed(new))
+            else:
+                w = self._tweak[0:4]
+                p = self._calc_p(i, w, A)
+                m = self._radix ** v
+                b_num = self._num(list(reversed(B)))
+                y = (b_num - p) % m
+                new = self._str(y, v)
+                B = list(reversed(new))
+
+        return A + B

cyphera-0.0.1a3/cyphera.egg-info/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: cyphera
+Version: 0.0.1a3
+Summary: Data protection SDK — format-preserving encryption (FF1/FF3), AES-GCM, data masking, and hashing.
+Author-email: Leslie Gutschow <leslie.gutschow@horizondigital.dev>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://cyphera.io
+Project-URL: Repository, https://github.com/cyphera-labs/cyphera-python
+Project-URL: Issues, https://github.com/cyphera-labs/cyphera-python/issues
+Keywords: encryption,fpe,format-preserving,data-protection,masking
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.9
+Requires-Dist: cryptography>=41.0

cyphera-0.0.1a3/cyphera.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+cyphera/__init__.py
+cyphera/ff1.py
+cyphera/ff3.py
+cyphera.egg-info/PKG-INFO
+cyphera.egg-info/SOURCES.txt
+cyphera.egg-info/dependency_links.txt
+cyphera.egg-info/requires.txt
+cyphera.egg-info/top_level.txt
+tests/test_ff1_nist.py
+tests/test_ff3_nist.py

cyphera-0.0.1a3/cyphera.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

cyphera-0.0.1a3/cyphera.egg-info/requires.txt

@@ -0,0 +1 @@
+cryptography>=41.0

cyphera-0.0.1a3/cyphera.egg-info/top_level.txt

@@ -0,0 +1 @@
+cyphera

cyphera-0.0.1a3/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "cyphera"
+version = "0.0.1a3"
+description = "Data protection SDK — format-preserving encryption (FF1/FF3), AES-GCM, data masking, and hashing."
+license = "Apache-2.0"
+requires-python = ">=3.9"
+dependencies = ["cryptography>=41.0"]
+authors = [
+    { name = "Leslie Gutschow", email = "leslie.gutschow@horizondigital.dev" },
+]
+keywords = ["encryption", "fpe", "format-preserving", "data-protection", "masking"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Topic :: Security :: Cryptography",
+]
+
+[project.urls]
+Homepage = "https://cyphera.io"
+Repository = "https://github.com/cyphera-labs/cyphera-python"
+Issues = "https://github.com/cyphera-labs/cyphera-python/issues"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

cyphera-0.0.1a3/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cyphera-0.0.1a3/tests/test_ff1_nist.py

@@ -0,0 +1,56 @@
+"""FF1 NIST SP 800-38G test vectors."""
+from cyphera.ff1 import FF1, DIGITS, ALPHANUMERIC
+
+
+def test_sample_1():
+    c = FF1(bytes.fromhex("2B7E151628AED2A6ABF7158809CF4F3C"), b"", DIGITS)
+    assert c.encrypt("0123456789") == "2433477484"
+    assert c.decrypt("2433477484") == "0123456789"
+
+
+def test_sample_2():
+    c = FF1(bytes.fromhex("2B7E151628AED2A6ABF7158809CF4F3C"), bytes.fromhex("39383736353433323130"), DIGITS)
+    assert c.encrypt("0123456789") == "6124200773"
+    assert c.decrypt("6124200773") == "0123456789"
+
+
+def test_sample_3():
+    c = FF1(bytes.fromhex("2B7E151628AED2A6ABF7158809CF4F3C"), bytes.fromhex("3737373770717273373737"), ALPHANUMERIC)
+    assert c.encrypt("0123456789abcdefghi") == "a9tv40mll9kdu509eum"
+    assert c.decrypt("a9tv40mll9kdu509eum") == "0123456789abcdefghi"
+
+
+def test_sample_4():
+    c = FF1(bytes.fromhex("2B7E151628AED2A6ABF7158809CF4F3CEF4359D8D580AA4F"), b"", DIGITS)
+    assert c.encrypt("0123456789") == "2830668132"
+    assert c.decrypt("2830668132") == "0123456789"
+
+
+def test_sample_5():
+    c = FF1(bytes.fromhex("2B7E151628AED2A6ABF7158809CF4F3CEF4359D8D580AA4F"), bytes.fromhex("39383736353433323130"), DIGITS)
+    assert c.encrypt("0123456789") == "2496655549"
+    assert c.decrypt("2496655549") == "0123456789"
+
+
+def test_sample_6():
+    c = FF1(bytes.fromhex("2B7E151628AED2A6ABF7158809CF4F3CEF4359D8D580AA4F"), bytes.fromhex("3737373770717273373737"), ALPHANUMERIC)
+    assert c.encrypt("0123456789abcdefghi") == "xbj3kv35jrawxv32ysr"
+    assert c.decrypt("xbj3kv35jrawxv32ysr") == "0123456789abcdefghi"
+
+
+def test_sample_7():
+    c = FF1(bytes.fromhex("2B7E151628AED2A6ABF7158809CF4F3CEF4359D8D580AA4F7F036D6F04FC6A94"), b"", DIGITS)
+    assert c.encrypt("0123456789") == "6657667009"
+    assert c.decrypt("6657667009") == "0123456789"
+
+
+def test_sample_8():
+    c = FF1(bytes.fromhex("2B7E151628AED2A6ABF7158809CF4F3CEF4359D8D580AA4F7F036D6F04FC6A94"), bytes.fromhex("39383736353433323130"), DIGITS)
+    assert c.encrypt("0123456789") == "1001623463"
+    assert c.decrypt("1001623463") == "0123456789"
+
+
+def test_sample_9():
+    c = FF1(bytes.fromhex("2B7E151628AED2A6ABF7158809CF4F3CEF4359D8D580AA4F7F036D6F04FC6A94"), bytes.fromhex("3737373770717273373737"), ALPHANUMERIC)
+    assert c.encrypt("0123456789abcdefghi") == "xs8a0azh2avyalyzuwd"
+    assert c.decrypt("xs8a0azh2avyalyzuwd") == "0123456789abcdefghi"

cyphera-0.0.1a3/tests/test_ff3_nist.py

@@ -0,0 +1,25 @@
+"""FF3 NIST SP 800-38G test vectors (all 15)."""
+from cyphera.ff3 import FF3, DIGITS
+
+R26 = "0123456789abcdefghijklmnop"
+
+def _t(key_hex, tweak_hex, alphabet, pt, ct):
+    c = FF3(bytes.fromhex(key_hex), bytes.fromhex(tweak_hex), alphabet)
+    assert c.encrypt(pt) == ct, f"encrypt({pt}) != {ct}"
+    assert c.decrypt(ct) == pt, f"decrypt({ct}) != {pt}"
+
+def test_s01(): _t("EF4359D8D580AA4F7F036D6F04FC6A94", "D8E7920AFA330A73", DIGITS, "890121234567890000", "750918814058654607")
+def test_s02(): _t("EF4359D8D580AA4F7F036D6F04FC6A94", "9A768A92F60E12D8", DIGITS, "890121234567890000", "018989839189395384")
+def test_s03(): _t("EF4359D8D580AA4F7F036D6F04FC6A94", "D8E7920AFA330A73", DIGITS, "89012123456789000000789000000", "48598367162252569629397416226")
+def test_s04(): _t("EF4359D8D580AA4F7F036D6F04FC6A94", "0000000000000000", DIGITS, "89012123456789000000789000000", "34695224821734535122613701434")
+def test_s05(): _t("EF4359D8D580AA4F7F036D6F04FC6A94", "9A768A92F60E12D8", R26, "0123456789abcdefghi", "g2pk40i992fn20cjakb")
+def test_s06(): _t("EF4359D8D580AA4F7F036D6F04FC6A942B7E151628AED2A6", "D8E7920AFA330A73", DIGITS, "890121234567890000", "646965393875028755")
+def test_s07(): _t("EF4359D8D580AA4F7F036D6F04FC6A942B7E151628AED2A6", "9A768A92F60E12D8", DIGITS, "890121234567890000", "961610514491424446")
+def test_s08(): _t("EF4359D8D580AA4F7F036D6F04FC6A942B7E151628AED2A6", "D8E7920AFA330A73", DIGITS, "89012123456789000000789000000", "53048884065350204541786380807")
+def test_s09(): _t("EF4359D8D580AA4F7F036D6F04FC6A942B7E151628AED2A6", "0000000000000000", DIGITS, "89012123456789000000789000000", "98083802678820389295041483512")
+def test_s10(): _t("EF4359D8D580AA4F7F036D6F04FC6A942B7E151628AED2A6", "9A768A92F60E12D8", R26, "0123456789abcdefghi", "i0ihe2jfj7a9opf9p88")
+def test_s11(): _t("EF4359D8D580AA4F7F036D6F04FC6A942B7E151628AED2A6ABF7158809CF4F3C", "D8E7920AFA330A73", DIGITS, "890121234567890000", "922011205562777495")
+def test_s12(): _t("EF4359D8D580AA4F7F036D6F04FC6A942B7E151628AED2A6ABF7158809CF4F3C", "9A768A92F60E12D8", DIGITS, "890121234567890000", "504149865578056140")
+def test_s13(): _t("EF4359D8D580AA4F7F036D6F04FC6A942B7E151628AED2A6ABF7158809CF4F3C", "D8E7920AFA330A73", DIGITS, "89012123456789000000789000000", "04344343235792599165734622699")
+def test_s14(): _t("EF4359D8D580AA4F7F036D6F04FC6A942B7E151628AED2A6ABF7158809CF4F3C", "0000000000000000", DIGITS, "89012123456789000000789000000", "30859239999374053872365555822")
+def test_s15(): _t("EF4359D8D580AA4F7F036D6F04FC6A942B7E151628AED2A6ABF7158809CF4F3C", "9A768A92F60E12D8", R26, "0123456789abcdefghi", "p0b2godfja9bhb7bk38")