fpr-ff1 0.1.0__py3-none-any.whl

fpr_ff1/__init__.py

@@ -0,0 +1,23 @@
+"""FF1 format-preserving encryption (NIST SP 800-38G)."""
+
+from fpr_ff1._exceptions import (
+    AlphabetError,
+    FF1Error,
+    KeyLengthError,
+    LengthError,
+    RadixError,
+    TweakLengthError,
+    ValueRangeError,
+)
+from fpr_ff1._ff1 import FF1
+
+__all__ = [
+    "FF1",
+    "AlphabetError",
+    "FF1Error",
+    "KeyLengthError",
+    "LengthError",
+    "RadixError",
+    "TweakLengthError",
+    "ValueRangeError",
+]

fpr_ff1/_exceptions.py

@@ -0,0 +1,34 @@
+"""Typed exceptions for the FF1 implementation."""
+
+
+class FF1Error(Exception):
+    """Base for all FF1 errors."""
+
+
+class KeyLengthError(FF1Error):
+    """Key length is not 16, 24, or 32 bytes."""
+
+
+class RadixError(FF1Error):
+    """Radix is outside ``2 <= radix < 2**16``."""
+
+
+class LengthError(FF1Error):
+    """Input length is outside the valid domain for the radix."""
+
+
+class ValueRangeError(FF1Error):
+    """Input data is outside the domain the instance accepts.
+
+    Raised for a numeral outside ``[0, radix)``, and for a character that does
+    not appear in the configured alphabet.  Both are faults in the *data* being
+    encrypted; malformed *configuration* raises :class:`AlphabetError` instead.
+    """
+
+
+class TweakLengthError(FF1Error):
+    """Tweak length is outside the configured bounds."""
+
+
+class AlphabetError(FF1Error):
+    """Alphabet length or uniqueness does not match the radix."""

fpr_ff1/_ff1.py

@@ -0,0 +1,549 @@
+"""FF1 implementation following NIST SP 800-38G Algorithm 7."""
+
+from __future__ import annotations
+
+import operator
+from collections.abc import Sequence
+from typing import ClassVar, NamedTuple, SupportsIndex, cast
+
+from cryptography.hazmat.primitives.ciphers import (
+    Cipher,
+    CipherContext,
+    algorithms,
+    modes,
+)
+
+from fpr_ff1._exceptions import (
+    AlphabetError,
+    FF1Error,
+    KeyLengthError,
+    LengthError,
+    RadixError,
+    TweakLengthError,
+    ValueRangeError,
+)
+
+#: One round's intermediate values, as published in the NIST sample document.
+#: Test-only; see :meth:`FF1._encrypt_traced`.
+type TraceRecord = dict[str, object]
+
+
+def _require_int(value: object, name: str, error: type[FF1Error]) -> int:
+    """Return ``value`` as an ``int``, rejecting anything not losslessly integral.
+
+    Uses ``operator.index()``, Python's own "this is an integer" protocol:
+    ``float`` and ``Decimal`` deliberately do not implement it, while ``int``,
+    ``IntEnum`` and NumPy integers do.  Comparison alone is not enough of a
+    gate -- ``1.0 < 10`` is ``True``, so a float numeral would otherwise pass
+    validation and fail much later with an ``AttributeError`` from outside the
+    :class:`FF1Error` hierarchy.
+
+    ``bool`` is rejected explicitly even though it implements ``__index__``:
+    silently encrypting ``True`` as ``1`` is the coercion the contract forbids,
+    and a sequence of booleans reaching this point is a caller mistake.
+
+    Converting rather than merely checking also normalises NumPy integers to
+    Python ``int``, which matters: fixed-width integers would overflow silently
+    in the big-integer arithmetic downstream.
+    """
+    if isinstance(value, bool):
+        raise error(f"{name} must be an integer, not bool")
+    try:
+        # The cast asserts only that __index__ *might* exist; TypeError below
+        # is the actual gate.
+        return operator.index(cast("SupportsIndex", value))
+    except TypeError:
+        raise error(f"{name} must be an integer, got {type(value).__name__}") from None
+
+
+def _validate_tweak_bounds(
+    min_tweak_len: int | None, max_tweak_len: int | None
+) -> tuple[int | None, int | None]:
+    """Type- and sanity-check the configured tweak length bounds.
+
+    These are *configuration* faults, distinct from a tweak that merely
+    violates an otherwise valid bound, and they are caught at construction so
+    an unusable instance can never be built.
+
+    Raises:
+        TweakLengthError: if a bound is not an integer, is negative, or if the
+            two bounds are mutually unsatisfiable.
+    """
+    low = (
+        None
+        if min_tweak_len is None
+        else _require_int(min_tweak_len, "min_tweak_len", TweakLengthError)
+    )
+    high = (
+        None
+        if max_tweak_len is None
+        else _require_int(max_tweak_len, "max_tweak_len", TweakLengthError)
+    )
+
+    for name, bound in (("min_tweak_len", low), ("max_tweak_len", high)):
+        if bound is not None and bound < 0:
+            # A negative bound is inert rather than harmful, but it silently
+            # means "no constraint" -- which is not what the caller asked for.
+            raise TweakLengthError(f"{name} must be non-negative, got {bound}")
+
+    if low is not None and high is not None and low > high:
+        raise TweakLengthError(
+            f"min_tweak_len {low} exceeds max_tweak_len {high}; "
+            "no tweak length could satisfy both bounds"
+        )
+
+    return low, high
+
+
+def _require_bytes(value: object, name: str, error: type[FF1Error]) -> bytes:
+    """Return ``value`` as ``bytes``, rejecting non-bytes-like input."""
+    if not isinstance(value, bytes | bytearray | memoryview):
+        raise error(f"{name} must be bytes-like, got {type(value).__name__}")
+    # Normalise to immutable bytes: a caller holding the bytearray must not be
+    # able to mutate a tweak or key after construction.
+    return bytes(cast("bytes | bytearray | memoryview[int]", value))
+
+
+class _Aes(NamedTuple):
+    """AES objects shared for the lifetime of one :class:`FF1` instance.
+
+    ``algorithm`` and ``cbc_zero_iv`` are immutable configuration, reused to
+    avoid rebuilding them on every PRF call.  ``ecb_encryptor`` is a live
+    context, but ECB carries no chaining state so repeated ``update()`` calls
+    are safe.  A CBC *encryptor* is never held here: it would carry chaining
+    state between PRF invocations.
+    """
+
+    algorithm: algorithms.AES
+    cbc_zero_iv: modes.CBC
+    ecb_encryptor: CipherContext
+
+
+class FF1:
+    """FF1 format-preserving encryption primitive and string wrapper."""
+
+    # SP 800-38G requires "minlen <= n <= maxlen < 2**32", so the largest
+    # admissible length is 2**32 - 1, not 2**32.  Failing closed on the
+    # boundary matches the project's stance elsewhere; the excluded value is
+    # unconstructable in practice (a 2**32-element list needs tens of GB).
+    _MAX_LEN: ClassVar[int] = 2**32 - 1
+    _RADIX_MIN: ClassVar[int] = 2
+    _RADIX_MAX_EXCLUSIVE: ClassVar[int] = 2**16
+
+    def __init__(
+        self,
+        key: bytes,
+        radix: int,
+        *,
+        alphabet: str | None = None,
+        tweak: bytes = b"",
+        min_tweak_len: int | None = None,
+        max_tweak_len: int | None = None,
+    ) -> None:
+        """Create an FF1 instance.
+
+        Args:
+            key: AES key; must be 16, 24, or 32 bytes.
+            radix: Numeral base, ``2 <= radix < 2**16``.
+            alphabet: Optional string of exactly ``radix`` unique characters.
+                Required for the string interface.
+            tweak: Default tweak used when not provided per call.
+            min_tweak_len: Optional inclusive lower bound on tweak length.
+            max_tweak_len: Optional inclusive upper bound on tweak length.
+
+        Raises:
+            KeyLengthError: if the key is not bytes-like or has an invalid length.
+            RadixError: if the radix is not an integer or is out of range.
+            TweakLengthError: if the tweak is not bytes-like or out of bounds.
+            AlphabetError: if the alphabet is not a string or is malformed.
+        """
+        # Types are checked before values throughout: a wrong type is the more
+        # fundamental fault, and reporting a range error for a float would be
+        # actively misleading.
+        key = _require_bytes(key, "key", KeyLengthError)
+        if len(key) not in {16, 24, 32}:
+            raise KeyLengthError(f"key must be 16, 24, or 32 bytes, got {len(key)}")
+
+        radix = _require_int(radix, "radix", RadixError)
+        if radix < self._RADIX_MIN or radix >= self._RADIX_MAX_EXCLUSIVE:
+            raise RadixError(
+                f"radix must satisfy {self._RADIX_MIN} <= radix < {self._RADIX_MAX_EXCLUSIVE}, "
+                f"got {radix!r}"
+            )
+
+        self._key = key
+        self._radix = radix
+
+        # Bounds are validated before the default tweak is checked against
+        # them, so an unsatisfiable configuration is reported as such rather
+        # than as whichever bound the default tweak happened to violate first.
+        self._min_tweak_len, self._max_tweak_len = _validate_tweak_bounds(
+            min_tweak_len, max_tweak_len
+        )
+        tweak = _require_bytes(tweak, "tweak", TweakLengthError)
+        self._validate_tweak(tweak)
+        self._default_tweak = tweak
+
+        self._alphabet: str | None = None
+        self._char_to_index: dict[str, int] | None = None
+        self._index_to_char: list[str] | None = None
+        if alphabet is not None:
+            # Checked at runtime despite the annotation: type hints are not
+            # enforced, and a list alphabet silently worked before this guard.
+            if not isinstance(alphabet, str):  # pyright: ignore[reportUnnecessaryIsInstance]
+                raise AlphabetError(f"alphabet must be a str, got {type(alphabet).__name__}")
+            if len(alphabet) != radix:
+                raise AlphabetError(f"alphabet length {len(alphabet)} does not match radix {radix}")
+            # Uniqueness is by Unicode code point.  Two visually identical but
+            # differently-normalised symbols (e.g. precomposed vs decomposed
+            # accents) are distinct here; normalisation is the caller's job.
+            if len(set(alphabet)) != len(alphabet):
+                raise AlphabetError("alphabet contains duplicate characters")
+            self._alphabet = alphabet
+            self._char_to_index = {ch: i for i, ch in enumerate(alphabet)}
+            self._index_to_char = list(alphabet)
+
+        # Every legal radix admits a feasible length: min_length peaks at 20
+        # (radix 2), far below _MAX_LEN, so no infeasibility check is needed.
+        self._min_length = _min_length(radix)
+
+        # Cipher objects reused across calls.  Do not call finalize() on the
+        # ECB encryptor; it must stay alive for the instance's lifetime.
+        algorithm = algorithms.AES(key)
+        self._aes = _Aes(
+            algorithm=algorithm,
+            cbc_zero_iv=modes.CBC(b"\x00" * 16),
+            ecb_encryptor=Cipher(algorithm, modes.ECB()).encryptor(),
+        )
+
+    @property
+    def min_length(self) -> int:
+        """Minimum permitted input length for this radix."""
+        return self._min_length
+
+    @property
+    def max_length(self) -> int:
+        """Maximum permitted input length for this radix.
+
+        ``2**32 - 1``: SP 800-38G specifies ``maxlen < 2**32``.
+        """
+        return self._MAX_LEN
+
+    def _validate_tweak(self, tweak: bytes) -> None:
+        if self._min_tweak_len is not None and len(tweak) < self._min_tweak_len:
+            raise TweakLengthError(f"tweak length {len(tweak)} below minimum {self._min_tweak_len}")
+        if self._max_tweak_len is not None and len(tweak) > self._max_tweak_len:
+            raise TweakLengthError(f"tweak length {len(tweak)} above maximum {self._max_tweak_len}")
+
+    def _validate_length(self, n: int, inout: str) -> None:
+        if n < self._min_length:
+            raise LengthError(
+                f"{inout} length {n} below minimum {self._min_length} for radix {self._radix}"
+            )
+        if n > self._MAX_LEN:
+            raise LengthError(f"{inout} length {n} above maximum {self._MAX_LEN}")
+
+    def _coerce_numerals(self, x: Sequence[int], inout: str) -> list[int]:
+        """Type-check, normalise and range-check numerals in a single pass.
+
+        Returns true Python ``int`` values, so fixed-width integers from other
+        numeric libraries cannot reach the big-integer arithmetic downstream
+        and overflow silently.
+        """
+        radix = self._radix
+        numerals: list[int] = []
+        for idx, value in enumerate(x):
+            numeral = _require_int(value, f"{inout}[{idx}]", ValueRangeError)
+            if numeral < 0 or numeral >= radix:
+                raise ValueRangeError(f"{inout}[{idx}]={numeral!r} out of range for radix {radix}")
+            numerals.append(numeral)
+        return numerals
+
+    def _prepare(
+        self, x: Sequence[int], tweak: bytes | None, inout: str
+    ) -> tuple[list[int], bytes]:
+        """Validate and normalise the inputs shared by encrypt and decrypt."""
+        t = (
+            self._default_tweak
+            if tweak is None
+            else _require_bytes(tweak, "tweak", TweakLengthError)
+        )
+        # Check the length before materialising the sequence: an over-long
+        # input must be rejected without first allocating a copy of it.
+        if not hasattr(x, "__len__"):
+            raise TypeError(
+                f"{inout} must be a Sequence[int] with a known length, got "
+                f"{type(x).__name__}; wrap it with list(...) if it is an iterator"
+            )
+        self._validate_length(len(x), inout)
+        numerals = self._coerce_numerals(x, inout)
+        self._validate_tweak(t)
+        return numerals, t
+
+    def _alphabet_maps(self, numeral_method: str) -> tuple[dict[str, int], list[str]]:
+        """Return the alphabet lookup tables, or raise if none was configured."""
+        if self._char_to_index is None or self._index_to_char is None:
+            raise FF1Error(
+                f"alphabet required for string interface; use {numeral_method} "
+                "for the numeral interface"
+            )
+        return self._char_to_index, self._index_to_char
+
+    def _decode_str(self, s: str, char_to_index: dict[str, int]) -> list[int]:
+        """Map characters to numerals, rejecting anything outside the alphabet."""
+        # Checked at runtime despite the annotation; see _require_int.
+        if not isinstance(s, str):  # pyright: ignore[reportUnnecessaryIsInstance]
+            raise ValueRangeError(f"input must be a str, got {type(s).__name__}")
+        numerals: list[int] = []
+        for idx, ch in enumerate(s):
+            value = char_to_index.get(ch)
+            if value is None:
+                raise ValueRangeError(f"character {ch!r} at index {idx} is not in the alphabet")
+            numerals.append(value)
+        return numerals
+
+    def encrypt_numerals(self, x: Sequence[int], tweak: bytes | None = None) -> list[int]:
+        """Encrypt a sequence of numerals.
+
+        Args:
+            x: List of integers in ``[0, radix)``.
+            tweak: Tweak bytes; defaults to the instance tweak.
+
+        Returns:
+            Encrypted numeral sequence of the same length.
+
+        Raises:
+            LengthError: if the input length is outside the valid domain.
+            ValueRangeError: if any numeral is outside ``[0, radix)``.
+            TweakLengthError: if the tweak is out of bounds.
+        """
+        numerals, t = self._prepare(x, tweak, "plaintext")
+        return _ff1(self._aes, self._radix, numerals, t, encrypt=True)
+
+    def decrypt_numerals(self, x: Sequence[int], tweak: bytes | None = None) -> list[int]:
+        """Decrypt a sequence of numerals.
+
+        Args:
+            x: List of integers in ``[0, radix)``.
+            tweak: Tweak bytes; defaults to the instance tweak.
+
+        Returns:
+            Decrypted numeral sequence of the same length.
+
+        Raises:
+            LengthError: if the input length is outside the valid domain.
+            ValueRangeError: if any numeral is outside ``[0, radix)``.
+            TweakLengthError: if the tweak is out of bounds.
+        """
+        numerals, t = self._prepare(x, tweak, "ciphertext")
+        return _ff1(self._aes, self._radix, numerals, t, encrypt=False)
+
+    def _encrypt_traced(
+        self, x: Sequence[int], tweak: bytes | None = None
+    ) -> tuple[list[int], list[TraceRecord]]:
+        """Encrypt, also returning the per-round intermediates.
+
+        Test-only conformance hook, deliberately kept off the public methods:
+        the NIST sample document publishes ``P``, ``Q``, ``R``, ``S``, ``y``,
+        ``m``, ``c`` and ``C`` for every round, and two compensating bugs can
+        agree on the final output while disagreeing here.
+
+        Not exported from the package and not part of the supported API.
+        """
+        numerals, t = self._prepare(x, tweak, "plaintext")
+        trace: list[TraceRecord] = []
+        return _ff1(self._aes, self._radix, numerals, t, encrypt=True, _trace=trace), trace
+
+    def encrypt(self, s: str, tweak: bytes | None = None) -> str:
+        """Encrypt a string using the configured alphabet.
+
+        Raises:
+            FF1Error: if no alphabet was configured at construction.
+            ValueRangeError: if a character is absent from the alphabet.
+        """
+        char_to_index, index_to_char = self._alphabet_maps("encrypt_numerals")
+        numerals = self._decode_str(s, char_to_index)
+        encrypted = self.encrypt_numerals(numerals, tweak)
+        return "".join(index_to_char[i] for i in encrypted)
+
+    def decrypt(self, s: str, tweak: bytes | None = None) -> str:
+        """Decrypt a string using the configured alphabet.
+
+        Raises:
+            FF1Error: if no alphabet was configured at construction.
+            ValueRangeError: if a character is absent from the alphabet.
+        """
+        char_to_index, index_to_char = self._alphabet_maps("decrypt_numerals")
+        numerals = self._decode_str(s, char_to_index)
+        decrypted = self.decrypt_numerals(numerals, tweak)
+        return "".join(index_to_char[i] for i in decrypted)
+
+
+_MIN_DOMAIN = 1_000_000
+
+
+def _min_length(radix: int) -> int:
+    """Return the smallest n with radix**n >= 1_000_000."""
+    n = 1
+    value = radix
+    while value < _MIN_DOMAIN:
+        value *= radix
+        n += 1
+    return n
+
+
+def _num_radix(radix: int, numerals: Sequence[int]) -> int:
+    """Decode a sequence of numerals as a big-endian base-radix integer."""
+    value = 0
+    for x in numerals:
+        value = value * radix + x
+    return value
+
+
+def _str_radix(value: int, radix: int, length: int) -> list[int]:
+    """Encode a non-negative integer as ``length`` big-endian base-radix numerals."""
+    out = [0] * length
+    for i in range(length - 1, -1, -1):
+        out[i] = value % radix
+        value //= radix
+    return out
+
+
+def _prf(aes: _Aes, data: bytes) -> bytes:
+    """SP 800-38G Algorithm 6 (PRF): CBC-MAC with a zero IV.
+
+    Invoked from Algorithm 7 step 6.ii as ``PRF(P || Q)``.
+    """
+    # data is already 16-byte aligned by callers.  A fresh encryptor per call
+    # is required: CBC chaining state must never persist between PRF calls.
+    encryptor = Cipher(aes.algorithm, aes.cbc_zero_iv).encryptor()
+    result = encryptor.update(data) + encryptor.finalize()
+    return result[-16:]
+
+
+def _ff1(
+    aes: _Aes,
+    radix: int,
+    x: list[int],
+    tweak: bytes,
+    *,
+    encrypt: bool,
+    _trace: list[TraceRecord] | None = None,
+) -> list[int]:
+    """SP 800-38G Algorithm 7 core."""
+    n = len(x)
+
+    # Step 1: u = floor(n/2), v = n - u
+    u = n // 2
+    v = n - u
+
+    # Step 2: A = X[1..u], B = X[u+1..n]
+    a = x[:u]
+    b_side = x[u:]
+
+    # Step 3: b = ceil(ceil(v * log2(radix)) / 8) -- derived from v, not u.
+    # The bit length uses exact integer arithmetic; never math.log2.
+    b = ((radix**v - 1).bit_length() + 7) // 8
+
+    # Step 4: d = 4 * ceil(b/4) + 4
+    d = 4 * ((b + 3) // 4) + 4
+
+    t = len(tweak)
+    pad = (-(t + b + 1)) % 16
+
+    # Step 5: P is loop-invariant, so it is built once here rather than
+    # rebuilt on each of the ten rounds.
+    p_block = (
+        bytes([1, 2, 1])
+        + _encode_uint(radix, 3)
+        + bytes([10, u % 256])
+        + _encode_uint(n, 4)
+        + _encode_uint(t, 4)
+    )
+
+    rounds = range(10) if encrypt else range(9, -1, -1)
+
+    for i in rounds:
+        # Step 6.i: Q = T || [0]^pad || [i]^1 || [NUM_radix(B)]^b
+        # (decrypt builds Q from A instead of B)
+        if encrypt:
+            q_block = (
+                tweak + bytes([0]) * pad + bytes([i]) + _encode_uint(_num_radix(radix, b_side), b)
+            )
+        else:
+            q_block = tweak + bytes([0]) * pad + bytes([i]) + _encode_uint(_num_radix(radix, a), b)
+
+        # Step 6.ii: R = PRF(P || Q)
+        r_block = _prf(aes, p_block + q_block)
+
+        # Step 6.iii: S is the first d bytes of
+        #   R || CIPH_K(R XOR [1]^16) || CIPH_K(R XOR [2]^16) || ...
+        # Each expansion block is a SINGLE forward-cipher block over R XOR the
+        # 16-byte encoding of j.  It is not a PRF, and j is not concatenated
+        # onto R -- both mistakes produce a non-16-byte-aligned input and are
+        # invisible to the NIST samples, none of which reach d > 16.
+        s_block = r_block
+        j = 1
+        while len(s_block) < d:
+            xored = bytes(p ^ q for p, q in zip(r_block, _encode_uint(j, 16), strict=True))
+            s_block += aes.ecb_encryptor.update(xored)
+            j += 1
+        # Truncate to d BYTES, not d bits.
+        s_block = s_block[:d]
+
+        # Step 6.iv: y = NUM(S)
+        y = int.from_bytes(s_block, byteorder="big")
+
+        # Step 6.v: parity rule is identical for encrypt and decrypt
+        m = u if i % 2 == 0 else v
+
+        # Step 6.vi: c = (NUM_radix(A) + y) mod radix**m  (decrypt subtracts
+        # y from NUM_radix(B) instead)
+        if encrypt:
+            c = (_num_radix(radix, a) + y) % (radix**m)
+        else:
+            c = (_num_radix(radix, b_side) - y) % (radix**m)
+
+        # Step 6.vii: C = STR^m_radix(c)
+        c_block = _str_radix(c, radix, m)
+
+        if _trace is not None:
+            _trace.append(
+                {
+                    "i": i,
+                    "u": u,
+                    "v": v,
+                    "b": b,
+                    "d": d,
+                    "P": list(p_block),
+                    "Q": list(q_block),
+                    "R": list(r_block),
+                    "S": list(s_block),
+                    "y": y,
+                    "m": m,
+                    "c": c,
+                    "C": list(c_block),
+                    "A_before": list(a),
+                    "B_before": list(b_side),
+                }
+            )
+
+        # Steps 6.viii and 6.ix: A = B, B = C  (decrypt assigns B = A, A = C)
+        if encrypt:
+            a = b_side
+            b_side = c_block
+        else:
+            b_side = a
+            a = c_block
+
+    # Step 7: return A || B
+    return a + b_side
+
+
+def _encode_uint(value: int, length: int) -> bytes:
+    """Encode a non-negative integer as a big-endian ``length``-byte string.
+
+    Raises ``OverflowError`` if the value does not fit, which is deliberate:
+    silently truncating would corrupt Q and produce non-conformant ciphertext.
+    """
+    return value.to_bytes(length, byteorder="big")

fpr_ff1-0.1.0.dist-info/METADATA

@@ -0,0 +1,348 @@
+Metadata-Version: 2.5
+Name: fpr-ff1
+Version: 0.1.0
+Summary: Format-preserving encryption: NIST SP 800-38G FF1 for Python.
+Project-URL: Homepage, https://github.com/joelee/fpr-ff1
+Project-URL: Repository, https://github.com/joelee/fpr-ff1
+Project-URL: Issues, https://github.com/joelee/fpr-ff1/issues
+Project-URL: Changelog, https://github.com/joelee/fpr-ff1/blob/main/CHANGELOG.md
+Project-URL: Security, https://github.com/joelee/fpr-ff1/blob/main/SECURITY.md
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cryptography,ff1,format-preserving-encryption,fpe,nist,sp800-38g
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Security :: Cryptography
+Classifier: Typing :: Typed
+Requires-Python: <3.15,>=3.12
+Requires-Dist: cryptography>=44.0.0
+Description-Content-Type: text/markdown
+
+# fpr-ff1
+
+A small, correct Python implementation of **FF1**, the format-preserving encryption mode from NIST SP 800-38G.
+
+This package is intentionally just the algorithm: no accounts, no network, no key management, and no FF3/FF3-1 modes.
+
+## Install
+
+```bash
+pip install fpr-ff1
+```
+
+## Quick start
+
+```python
+from fpr_ff1 import FF1
+
+ff1 = FF1(
+    key=b"\x00" * 16,
+    radix=10,
+    alphabet="0123456789",
+    tweak=b"",
+)
+
+encrypted = ff1.encrypt("123456")
+decrypted = ff1.decrypt(encrypted)
+assert decrypted == "123456"
+```
+
+## Features
+
+- Pure Python with a single runtime dependency: `cryptography`.
+- Conformance-tested against the NIST SP 800-38G sample vectors.
+- No floating-point arithmetic in the FF1 core.
+- Tightened domain limits from the SP 800-38G Rev. 1 second public draft:
+  - radix range `2 <= radix < 2**16`
+  - minimum domain `radix ** minlen >= 1_000_000`
+  - maximum length `2 ** 32 - 1` (SP 800-38G specifies `maxlen < 2 ** 32`)
+  - AES keys of 128, 192, or 256 bits only
+- Strongly typed public API with typed exceptions rooted at `FF1Error`.
+
+## Why you can trust this implementation
+
+Format-preserving encryption is unusually easy to get *almost* right. A subtly wrong FF1 still
+round-trips perfectly — `decrypt(encrypt(x)) == x` — while producing ciphertext no conformant
+implementation can read. By the time anyone notices, the data is written. So conformance here is
+not a checkbox; it is the entire product, and it is evidenced rather than asserted.
+
+**708 tests. 100% line and branch coverage, enforced — the build fails below it.**
+
+### Conformance is proven at the round level, not just the output level
+
+All nine published NIST sample vectors pass in both directions. That alone is a weak statement:
+nine input/output pairs can be satisfied by two bugs that cancel out.
+
+So this package also asserts the **per-round intermediate values** the NIST sample document
+publishes — `P`, `Q`, `R`, `S`, `y`, `m`, `c` and `C`, plus the derived `u`, `v`, `b` and `d` — for
+**every round of every sample**, 90 rounds in total. Compensating bugs survive an output test. They
+do not survive this one.
+
+The vectors are transcribed from the NIST document and stored as data files. They are never
+regenerated from this implementation, which would make them a record of whatever the code does
+rather than of what the standard requires.
+
+### Radices without published vectors are proven against an independent implementation
+
+NIST publishes vectors for radix 10 and 36 only. Every other radix has none, so agreement with an
+independent implementation is the only correctness evidence available — expected values authored
+from this code would test nothing and lock in any bug permanently.
+
+`fpr-ff1` is therefore differential-tested against `ubiq_security_fpe` across radices **2, 10, 16,
+32, 36, 62, 256 and 65535**, including every length where the algorithm's internal block structure
+changes. The oracle is itself validated against all nine NIST vectors before a single comparison is
+trusted.
+
+### Bijectivity is verified exhaustively, not sampled
+
+For two domains small enough to enumerate completely — radix 2 at length 20 (1,048,576 values) and
+radix 10 at length 6 (1,000,000 values) — every point is encrypted and the image checked to be the
+full domain, with no gaps and no collisions. That is the strongest correctness statement available
+for a permutation, and it is run in CI rather than kept as a manual check.
+
+### The known failure modes are tested for by name
+
+Published FF1 bugs cluster in a few places. Each has a dedicated test:
+
+| Known failure mode | How it is prevented |
+|---|---|
+| Floating-point `ceil(v · log₂(radix))` — the Bouncy Castle bug class | Exact integer arithmetic; an AST scan fails the build if `math.log`, `ceil`, `/` or any float literal appears in the core |
+| `b` derived from `u` instead of `v` | Asserted against the traced value, not a round-trip — which passes either way |
+| Wrong `S` expansion when `d > 16` | Differential cases at each block-count transition; no NIST sample reaches this branch |
+| Mirrored parity rule in decrypt | Encrypt and decrypt share one code path for it |
+| Silent coercion of bad input | Every rejection raises a typed exception; a 50-case sweep asserts nothing escapes as a bare `AttributeError` or `KeyError` |
+
+### Migration is safe by construction
+
+Output is byte-identical to `ubiq_security_fpe`, verified in **both** directions — old ciphertext
+decrypts with this library, and new ciphertext decrypts with the old one. Existing encrypted data
+stays readable, and a rollback strands nothing. See [Migrating](#migrating-from-ubiq_security_fpe).
+
+### What this is *not*
+
+Passing the published sample vectors is **conformance evidence, not FIPS validation**. This package
+is not FIPS 140 validated and makes no such claim. It also does not attempt key zeroization, and
+offers no constant-time guarantee — see [`SECURITY.md`](SECURITY.md) for the full statement of
+limitations.
+
+## Why FF1 only — and why FF3 is excluded
+
+SP 800-38G originally specified two modes, FF1 and FF3. FF3 was revised to FF3-1 after an attack
+on the original construction, but Beyne subsequently demonstrated a weakness in the **tweak
+schedule** that affects FF3 and FF3-1 alike — the repair did not address the underlying problem.
+
+The **February 2025 second public draft of SP 800-38G Rev. 1 removes FF3 entirely**, leaving FF1
+as the only approved format-preserving mode.
+
+`fpr-ff1` will therefore never implement FF3 or FF3-1. This is a deliberate feature, not an
+omission: there is no configuration flag, no opt-in, and no plan to add one. If you need FF3 you
+need a different library, and you should first satisfy yourself that you actually need a mode
+NIST has withdrawn.
+
+## Domain limits are stricter than the 2016 text
+
+This package implements SP 800-38G (2016, updated 2019) as the normative algorithm, but enforces
+the **tightened constraints from the Rev. 1 second public draft**:
+
+| Constraint | This package | SP 800-38G (2016) |
+|---|---|---|
+| Minimum domain | `radix ** minlen >= 1_000_000` | `radix ** minlen >= 100` |
+| Maximum length | `2 ** 32 - 1` | `2 ** 32 - 1` |
+| Key sizes | 128, 192, 256 bits | same |
+| Radix | `2 <= radix < 2 ** 16` | same |
+| Rounds | exactly 10 | same |
+
+The minimum-domain rule is the one that will bite. A domain of only 100 values is trivially
+enumerable, so this package **fails closed** and rejects it. Concretely, `min_length` is 6 for
+radix 10 and 4 for radix 36 — inputs shorter than that raise `LengthError`, even though some
+older libraries (including `ubiq_security_fpe`) accept them.
+
+Rev. 1 is still a draft. If it is finalised with different limits, that will be a breaking change
+and a major version.
+
+## Scope
+
+- **In scope:** FF1 encryption and decryption, numeral and string interfaces, alphabet handling, parameter validation, tests, documentation.
+- **Out of scope, permanently:** FF3/FF3-1, identifier generation, persistence, checksums, key generation/storage/derivation, application-specific defaults or alphabets.
+
+## Supported Python versions
+
+**3.12, 3.13 and 3.14.** The upper bound in `requires-python` is deliberate: it matches the
+versions actually exercised in CI on Linux, macOS and Windows. It is raised as part of a release
+once a newer Python is in the matrix and green, rather than being left open and assumed to work.
+
+## Roadmap
+
+| Version | Focus |
+|---|---|
+| **1.0** | **Pure Python.** Conformance, a stable API, and a single runtime dependency (`cryptography`). No compiled extension, no optional backends — one code path, and it is the one the vectors test. |
+| **2.0** | **Optional accelerated backend.** An opt-in faster path for high-throughput callers, with the pure-Python implementation retained as the reference and the default. |
+
+The 2.0 backend is explicitly *not* a 1.0 concern. An accelerated path is only worth having once
+the reference implementation is settled and there is a conformance suite strong enough to prove
+the two agree bit for bit — which is the point of the differential and interoperability tests.
+
+Nothing in the roadmap changes the scope boundary above. FF3 and FF3-1 remain permanently out of
+scope, and no release will add key management.
+
+## API
+
+### `FF1(key, radix, *, alphabet=None, tweak=b"", min_tweak_len=None, max_tweak_len=None)`
+
+| Parameter | Description |
+|---|---|
+| `key` | 16, 24, or 32 bytes. |
+| `radix` | Integer base of the numeral system. |
+| `alphabet` | Optional string of exactly `radix` unique characters; enables `encrypt`/`decrypt`. |
+| `tweak` | Default tweak used when not supplied per call. |
+| `min_tweak_len` / `max_tweak_len` | Optional per-instance tweak length bounds. |
+
+### Numeral interface
+
+The primitive interface works on integers in `[0, radix)`.
+
+```python
+ciphertext = ff1.encrypt_numerals([1, 2, 3, 4, 5, 6])
+plaintext = ff1.decrypt_numerals(ciphertext)
+```
+
+**Accepted numeral types.** Anything losslessly integral — `int`, `IntEnum`, and integers from
+other numeric libraries such as NumPy, which are normalised to Python `int` so fixed-width values
+cannot overflow in the internal big-integer arithmetic.
+
+`float`, `Decimal`, `Fraction` and `str` are **rejected** with `ValueRangeError`, even when they
+compare equal to a valid numeral: `1.0 < 10` is `True`, so comparison alone is not a type check.
+
+`bool` is **rejected deliberately**. `True` would otherwise encrypt silently as `1`, and a list of
+booleans arriving here is a caller mistake, not an intent to encrypt ones and zeros.
+
+The input must be a `Sequence` — something with a known length. A generator raises `TypeError`
+(not `FF1Error`), because that is misuse of the API rather than bad data; wrap it in `list(...)`.
+
+### String interface
+
+When `alphabet` is provided, the string interface maps characters to numerals and back.
+
+```python
+ff1.encrypt("123456")
+ff1.decrypt("654321")
+```
+
+**Alphabet uniqueness is by Unicode code point.** FF1 operates on code points, so normalisation is
+the caller's responsibility. Precomposed `é` (U+00E9) and decomposed `é` (U+0065 U+0301) are
+visually identical but count as two distinct symbols, and an alphabet containing both is accepted.
+If your alphabet comes from user input or an external source, normalise it first:
+
+```python
+import unicodedata
+alphabet = unicodedata.normalize("NFC", alphabet)
+```
+
+### Exceptions
+
+Every rejection raises a typed exception derived from `FF1Error`. Nothing is silently truncated,
+padded, coerced or clamped.
+
+| Exception | Raised when |
+|---|---|
+| `KeyLengthError` | key is not 16, 24 or 32 bytes |
+| `RadixError` | radix outside `2 <= radix < 2**16` |
+| `LengthError` | input length outside `[min_length, max_length]` |
+| `ValueRangeError` | a numeral outside `[0, radix)`, or a character absent from the alphabet |
+| `TweakLengthError` | tweak outside the configured bounds |
+| `AlphabetError` | alphabet length mismatched to radix, or containing duplicates |
+
+`AlphabetError` signals malformed *configuration* (caught at construction); `ValueRangeError`
+signals malformed *data* (caught per call). They are deliberately distinct so callers can handle
+a programming error differently from a bad input record.
+
+## Migrating from `ubiq_security_fpe`
+
+`fpr-ff1` exists to replace `ubiq_security_fpe`, which was deprecated in favour of a SaaS client
+and is no longer maintained. **The two produce identical ciphertext for identical inputs**, so
+existing encrypted data stays readable — no re-encryption, no migration window, no rollback risk.
+
+That claim is enforced by `tests/test_interoperability.py`, which checks both directions (old
+ciphertext decrypts with the new library and vice versa) across all three key sizes, tweaked and
+untweaked. Migration safety is treated as a correctness obligation, not a promise.
+
+**No compatibility shim ships, deliberately.** A `Context(...)` / `.Encrypt()` drop-in would mean
+maintaining a permanent second API, in a naming style this project does not use, mirroring a
+library that is itself deprecated. The migration below is three mechanical edits per call site,
+and the part that would actually be hard — identical ciphertext — is already done.
+
+### API mapping
+
+```python
+# before
+from ubiq_security_fpe import ff1
+ctx = ff1.Context(key, tweak, twk_min_len, twk_max_len, radix, alphabet)
+ciphertext = ctx.Encrypt(plaintext, None)
+plaintext  = ctx.Decrypt(ciphertext, None)
+
+# after
+from fpr_ff1 import FF1
+ctx = FF1(key, radix, alphabet=alphabet, tweak=tweak,
+          min_tweak_len=twk_min_len, max_tweak_len=twk_max_len)
+ciphertext = ctx.encrypt(plaintext)
+plaintext  = ctx.decrypt(ciphertext)
+```
+
+| `ubiq_security_fpe` | `fpr-ff1` |
+|---|---|
+| `ff1.Context(key, twk, twk_min_len, twk_max_len, radix, alpha)` | `FF1(key, radix, alphabet=..., tweak=..., min_tweak_len=..., max_tweak_len=...)` |
+| `ctx.Encrypt(pt, twk)` | `ctx.encrypt(pt, twk)` |
+| `ctx.Decrypt(ct, twk)` | `ctx.decrypt(ct, twk)` |
+| — | `ctx.encrypt_numerals(...)` / `ctx.decrypt_numerals(...)` (no alphabet needed) |
+| `RuntimeError` for every rejection | typed exceptions under `FF1Error` |
+
+### Behaviour changes to check before you switch
+
+1. **Shorter inputs are rejected.** `fpr-ff1` enforces `radix ** minlen >= 1_000_000`; the legacy
+   library used the same rule, but if you relied on any library using the 2016 `>= 100` bound,
+   inputs below `ctx.min_length` now raise `LengthError`. Check `ctx.min_length` for your radix.
+2. **Errors are typed.** Rejections raise `KeyLengthError`, `RadixError`, `LengthError`,
+   `ValueRangeError`, `TweakLengthError` or `AlphabetError` — all subclasses of `FF1Error` —
+   rather than bare `RuntimeError`. Catch `FF1Error` if you want the old catch-all behaviour.
+3. **No `M2Crypto` dependency.** `fpr-ff1` depends only on `cryptography`.
+4. **Alphabet is validated at construction.** A wrong-length alphabet or one with duplicate
+   characters raises `AlphabetError` immediately rather than misbehaving later.
+
+## FIPS disclaimer
+
+Passing the published NIST sample vectors is evidence of conformance. It is **not** FIPS validation. This package makes no claims of FIPS 140 conformance.
+
+## Key material
+
+`fpr-ff1` does not attempt to zeroize key material. Python `bytes` are immutable and the interpreter may copy them during garbage collection.
+
+## Development
+
+Requires Python 3.12, `uv`, and `just`.
+
+```bash
+just setup    # create venv and install deps
+just quality  # format check, lint, typecheck, tests
+just build    # quality gate + uv build
+just secrets  # gitleaks scan (must be installed locally)
+```
+
+## Documentation
+
+- `docs/architecture.md` — design and module overview
+- `docs/developer-guide.md` — setup, commands, testing, and CI
+- `docs/directory-structure.md` — repository layout
+- `docs/configuration.md` — `FF1` constructor parameters and runtime constraints
+- `docs/backlog.md` — active and completed work
+- `CHANGELOG.md` — release history, including behaviour changes that affect accepted inputs
+- `SECURITY.md` — disclosure process and known limitations
+
+## License
+
+MIT

fpr_ff1-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+fpr_ff1/__init__.py,sha256=kbnpTIr-F_D9Cp2_5QVcIL9GxT2twJ_HyckTbnA8T40,422
+fpr_ff1/_exceptions.py,sha256=kCUG4KYiwsjiGLkespCJsPSnXvD1_pRp7Ke7VxfQSLk,913
+fpr_ff1/_ff1.py,sha256=DfYAciuBIkIzO0SklMWxM2pgFgCS670eMvggwiwdaVg,21545
+fpr_ff1/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fpr_ff1-0.1.0.dist-info/METADATA,sha256=ECH4p073Xk3KoJTT98iynfEjyy1NrceX_OWvfZYzGDg,16289
+fpr_ff1-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+fpr_ff1-0.1.0.dist-info/licenses/LICENSE,sha256=FGQ9O0FIhqnsoDFIFBbwJXU_T9LEJnVeU6KRLn0Vs-I,1065
+fpr_ff1-0.1.0.dist-info/RECORD,,

fpr_ff1-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

fpr_ff1-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joel Lee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.