Initial: FF1 + FF3 with all 24 NIST vectors passing, pure Python

Author: lgutschow

.github/workflows/ci.yml

@@ -0,0 +1,13 @@
+name: CI
+on:
+  push: { branches: [main] }
+  pull_request: { branches: [main] }
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install -e ".[dev]" cryptography pytest
+      - run: pytest -v

.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/

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/__init__.py

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

cyphera/ff1.py

@@ -0,0 +1,143 @@
+"""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)
+        prev = r
+        for j in range(1, blocks):
+            x = j.to_bytes(16, "big")
+            x = bytes(a ^ b for a, b in zip(x, prev))
+            enc = self._aes_ecb(x)
+            out.extend(enc)
+            prev = 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/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

pyproject.toml

@@ -0,0 +1,17 @@
+[project]
+name = "cyphera"
+version = "0.1.0"
+description = "Data obfuscation SDK — FPE, AES, masking, hashing"
+license = "Apache-2.0"
+requires-python = ">=3.9"
+dependencies = ["cryptography>=41.0"]
+
+[project.urls]
+Repository = "https://github.com/cyphera-labs/cyphera-python"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

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"