fast-cipher 0.1.0__py3-none-any.whl

fast_cipher/__init__.py

@@ -0,0 +1,29 @@
+from .cipher import FastCipher
+from .params import calculate_recommended_params
+from .types import (
+    FastError,
+    FastParams,
+    InvalidBranchDistError,
+    InvalidKeyError,
+    InvalidLengthError,
+    InvalidParametersError,
+    InvalidRadixError,
+    InvalidSBoxCountError,
+    InvalidValueError,
+    InvalidWordLengthError,
+)
+
+__all__ = [
+    "FastCipher",
+    "FastError",
+    "FastParams",
+    "InvalidBranchDistError",
+    "InvalidKeyError",
+    "InvalidLengthError",
+    "InvalidParametersError",
+    "InvalidRadixError",
+    "InvalidSBoxCountError",
+    "InvalidValueError",
+    "InvalidWordLengthError",
+    "calculate_recommended_params",
+]

fast_cipher/cipher.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+from .core import cdec, cenc
+from .encoding import build_setup1_input, build_setup2_input
+from .prf import derive_key
+from .prng import generate_sequence
+from .sbox import generate_sbox_pool
+from .types import (
+    FastParams,
+    InvalidBranchDistError,
+    InvalidKeyError,
+    InvalidLengthError,
+    InvalidRadixError,
+    InvalidSBoxCountError,
+    InvalidValueError,
+    InvalidWordLengthError,
+)
+
+DERIVED_KEY_SIZE = 32
+
+
+class FastCipher:
+    """FAST format-preserving encryption cipher."""
+
+    def __init__(self, params: FastParams, key: bytes) -> None:
+        _validate_params(params, key)
+        self.params = params
+        self._master_key = bytes(key)
+
+        pool_key_material = derive_key(
+            key, build_setup1_input(params), DERIVED_KEY_SIZE
+        )
+        self._sboxes = generate_sbox_pool(
+            params.radix, params.sbox_count, bytes(pool_key_material)
+        )
+
+        self._cached_tweak: bytes | None = None
+        self._cached_seq: list[int] | None = None
+        self._destroyed = False
+
+    def _ensure_sequence(self, tweak: bytes) -> list[int]:
+        if self._cached_seq is not None and self._cached_tweak == tweak:
+            return self._cached_seq
+
+        seq_key_material = derive_key(
+            self._master_key,
+            build_setup2_input(self.params, tweak),
+            DERIVED_KEY_SIZE,
+        )
+        seq = generate_sequence(
+            self.params.num_layers,
+            self.params.sbox_count,
+            bytes(seq_key_material),
+        )
+        self._cached_tweak = tweak
+        self._cached_seq = seq
+        return seq
+
+    def _assert_alive(self) -> None:
+        if self._destroyed:
+            raise RuntimeError("FastCipher has been destroyed")
+
+    def _validate_input(self, data: bytes | list[int]) -> list[int]:
+        values = list(data)
+        if len(values) != self.params.word_length:
+            raise InvalidLengthError(
+                f"Expected {self.params.word_length} elements, got {len(values)}"
+            )
+        for v in values:
+            if not (0 <= v < self.params.radix):
+                raise InvalidValueError(
+                    f"Value {v} out of range [0, {self.params.radix})"
+                )
+        return values
+
+    def encrypt(self, plaintext: bytes | list[int], tweak: bytes = b"") -> list[int]:
+        self._assert_alive()
+        values = self._validate_input(plaintext)
+        seq = self._ensure_sequence(tweak)
+        return cenc(self.params, self._sboxes, seq, values)
+
+    def decrypt(self, ciphertext: bytes | list[int], tweak: bytes = b"") -> list[int]:
+        self._assert_alive()
+        values = self._validate_input(ciphertext)
+        seq = self._ensure_sequence(tweak)
+        return cdec(self.params, self._sboxes, seq, values)
+
+    def encrypt_bytes(self, plaintext: bytes, tweak: bytes = b"") -> bytes:
+        return bytes(self.encrypt(plaintext, tweak))
+
+    def decrypt_bytes(self, ciphertext: bytes, tweak: bytes = b"") -> bytes:
+        return bytes(self.decrypt(ciphertext, tweak))
+
+    def destroy(self) -> None:
+        self._destroyed = True
+        self._master_key = b"\x00" * len(self._master_key)
+        self._sboxes = []
+        self._cached_seq = None
+        self._cached_tweak = None
+
+
+def _validate_params(params: FastParams, key: bytes) -> None:
+    if params.radix < 4 or params.radix > 256:
+        raise InvalidRadixError("Radix must be between 4 and 256")
+
+    if params.word_length < 1:
+        raise InvalidWordLengthError("Word length must be >= 1")
+
+    if params.num_layers < 1:
+        raise InvalidWordLengthError("num_layers must be >= 1")
+
+    if params.word_length > 1 and params.num_layers % params.word_length != 0:
+        raise InvalidWordLengthError("num_layers must be a multiple of word_length")
+
+    if params.sbox_count < 1:
+        raise InvalidSBoxCountError("S-box count must be >= 1")
+
+    if params.branch_dist1 < 0:
+        raise InvalidBranchDistError("branch_dist1 must be >= 0")
+
+    if params.branch_dist2 < 0:
+        raise InvalidBranchDistError("branch_dist2 must be >= 0")
+
+    if params.word_length > 1:
+        if params.branch_dist1 > params.word_length - 2:
+            raise InvalidBranchDistError("branch_dist1 must be <= word_length - 2")
+        if params.branch_dist2 == 0 or params.branch_dist2 > params.word_length - 1:
+            raise InvalidBranchDistError("branch_dist2 is out of valid range")
+
+    if len(key) not in (16, 24, 32):
+        raise InvalidKeyError("Key must be 16, 24, or 32 bytes")

fast_cipher/core.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from .layers import ds_layer, es_layer
+from .sbox import SBox
+from .types import FastParams
+
+
+def cenc(
+    params: FastParams,
+    sboxes: list[SBox],
+    seq: list[int],
+    plaintext: list[int],
+) -> list[int]:
+    """Component encryption: apply all ES layers in forward order."""
+    data = list(plaintext)
+    if params.word_length == 1:
+        for layer in range(params.num_layers):
+            data[0] = sboxes[seq[layer]].perm[data[0]]
+        return data
+    for layer in range(params.num_layers):
+        es_layer(params, sboxes[seq[layer]], data)
+    return data
+
+
+def cdec(
+    params: FastParams,
+    sboxes: list[SBox],
+    seq: list[int],
+    ciphertext: list[int],
+) -> list[int]:
+    """Component decryption: apply all DS layers in reverse order."""
+    data = list(ciphertext)
+    if params.word_length == 1:
+        for layer in range(params.num_layers - 1, -1, -1):
+            data[0] = sboxes[seq[layer]].inv[data[0]]
+        return data
+    for layer in range(params.num_layers - 1, -1, -1):
+        ds_layer(params, sboxes[seq[layer]], data)
+    return data

fast_cipher/encoding.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import struct
+
+from .types import FastParams
+
+_LABEL_INSTANCE1 = b"instance1"
+_LABEL_INSTANCE2 = b"instance2"
+_LABEL_FPE_POOL = b"FPE Pool"
+_LABEL_FPE_SEQ = b"FPE SEQ"
+_LABEL_TWEAK = b"tweak"
+
+
+def _u32be(value: int) -> bytes:
+    return struct.pack(">I", value)
+
+
+def encode_parts(parts: list[bytes]) -> bytes:
+    buf = bytearray(_u32be(len(parts)))
+    for part in parts:
+        buf.extend(_u32be(len(part)))
+        buf.extend(part)
+    return bytes(buf)
+
+
+def build_setup1_input(params: FastParams) -> bytes:
+    return encode_parts(
+        [
+            _LABEL_INSTANCE1,
+            _u32be(params.radix),
+            _u32be(params.sbox_count),
+            _LABEL_FPE_POOL,
+        ]
+    )
+
+
+def build_setup2_input(params: FastParams, tweak: bytes) -> bytes:
+    return encode_parts(
+        [
+            _LABEL_INSTANCE1,
+            _u32be(params.radix),
+            _u32be(params.sbox_count),
+            _LABEL_INSTANCE2,
+            _u32be(params.word_length),
+            _u32be(params.num_layers),
+            _u32be(params.branch_dist1),
+            _u32be(params.branch_dist2),
+            _LABEL_FPE_SEQ,
+            _LABEL_TWEAK,
+            tweak,
+        ]
+    )

fast_cipher/layers.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from .sbox import SBox
+from .types import FastParams
+
+
+def _mod_add(a: int, b: int, radix: int) -> int:
+    if radix == 256:
+        return (a + b) & 0xFF
+    return (a + b) % radix
+
+
+def _mod_sub(a: int, b: int, radix: int) -> int:
+    if radix == 256:
+        return (a - b) & 0xFF
+    return (a - b) % radix
+
+
+def es_layer(params: FastParams, sbox: SBox, data: list[int]) -> None:
+    """ES (Expansion-Substitution) forward layer."""
+    w = params.branch_dist1
+    wp = params.branch_dist2
+    ell = params.word_length
+    radix = params.radix
+    perm = sbox.perm
+
+    s = perm[_mod_add(data[0], data[ell - wp], radix)]
+    if w > 0:
+        nxt = perm[_mod_sub(s, data[w], radix)]
+    else:
+        nxt = perm[s]
+
+    # Shift left by 1
+    data[:-1] = data[1:]
+    data[ell - 1] = nxt
+
+
+def ds_layer(params: FastParams, sbox: SBox, data: list[int]) -> None:
+    """DS (De-Substitution) backward layer."""
+    w = params.branch_dist1
+    wp = params.branch_dist2
+    ell = params.word_length
+    radix = params.radix
+    inv = sbox.inv
+
+    last = inv[data[ell - 1]]
+    if w > 0:
+        intermediate = inv[_mod_add(last, data[w - 1], radix)]
+    else:
+        intermediate = inv[last]
+    nxt = _mod_sub(intermediate, data[ell - wp - 1], radix)
+
+    # Shift right by 1
+    data[1:] = data[:-1]
+    data[0] = nxt

fast_cipher/params.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+import math
+
+from .types import FastParams, InvalidParametersError
+
+SBOX_POOL_SIZE = 256
+
+ROUND_L_VALUES = [2, 3, 4, 5, 6, 7, 8, 9, 10, 12, 16, 32, 50, 64, 100]
+ROUND_RADICES = [
+    4,
+    5,
+    6,
+    7,
+    8,
+    9,
+    10,
+    11,
+    12,
+    13,
+    14,
+    15,
+    16,
+    100,
+    128,
+    256,
+    1000,
+    1024,
+    10000,
+    65536,
+]
+
+ROUND_TABLE = [
+    [165, 135, 117, 105, 96, 89, 83, 78, 74, 68, 59, 52, 52, 53, 57],
+    [131, 107, 93, 83, 76, 70, 66, 62, 59, 54, 48, 46, 47, 48, 53],
+    [113, 92, 80, 72, 65, 61, 57, 54, 51, 46, 44, 43, 44, 46, 52],
+    [102, 83, 72, 64, 59, 55, 51, 48, 46, 43, 41, 41, 43, 45, 50],
+    [94, 76, 66, 59, 54, 50, 47, 44, 42, 41, 39, 39, 42, 44, 50],
+    [88, 72, 62, 56, 51, 47, 44, 42, 40, 39, 38, 38, 41, 43, 49],
+    [83, 68, 59, 53, 48, 45, 42, 39, 39, 38, 37, 37, 40, 43, 49],
+    [79, 65, 56, 50, 46, 43, 40, 38, 38, 37, 36, 37, 40, 42, 48],
+    [76, 62, 54, 48, 44, 41, 38, 37, 37, 36, 35, 36, 39, 42, 48],
+    [73, 60, 52, 47, 43, 39, 37, 36, 36, 35, 34, 36, 39, 41, 48],
+    [71, 58, 50, 45, 41, 38, 36, 36, 35, 34, 34, 35, 39, 41, 47],
+    [69, 57, 49, 44, 40, 37, 36, 35, 34, 34, 33, 35, 38, 41, 47],
+    [67, 55, 48, 43, 39, 36, 35, 34, 34, 33, 33, 35, 38, 41, 47],
+    [40, 33, 28, 27, 26, 26, 25, 25, 25, 26, 26, 30, 34, 37, 44],
+    [38, 31, 27, 26, 25, 25, 25, 25, 25, 25, 26, 30, 34, 37, 44],
+    [33, 27, 25, 24, 23, 23, 23, 23, 23, 24, 25, 29, 33, 37, 44],
+    [32, 22, 21, 21, 21, 21, 21, 21, 21, 22, 23, 28, 32, 36, 43],
+    [32, 22, 21, 21, 21, 21, 21, 21, 21, 22, 23, 28, 32, 36, 43],
+    [32, 22, 18, 18, 18, 18, 19, 19, 19, 20, 21, 27, 32, 35, 42],
+    [32, 22, 17, 17, 17, 17, 17, 18, 18, 19, 21, 26, 31, 35, 42],
+]
+
+
+def _interpolate(x: float, x0: float, x1: float, y0: float, y1: float) -> float:
+    if x1 == x0:
+        return y0
+    ratio = (x - x0) / (x1 - x0)
+    if ratio <= 0:
+        return y0
+    if ratio >= 1:
+        return y1
+    return y0 + ratio * (y1 - y0)
+
+
+def _rounds_for_row(row_index: int, ell: int) -> float:
+    row = ROUND_TABLE[row_index]
+    last_index = len(ROUND_L_VALUES) - 1
+    max_word_length = ROUND_L_VALUES[last_index]
+
+    if ell <= ROUND_L_VALUES[0]:
+        return row[0]
+
+    if ell >= max_word_length:
+        base_rounds = row[last_index]
+        return max(base_rounds, base_rounds * math.sqrt(ell / max_word_length))
+
+    for i in range(1, last_index + 1):
+        if ell <= ROUND_L_VALUES[i]:
+            return _interpolate(
+                ell,
+                ROUND_L_VALUES[i - 1],
+                ROUND_L_VALUES[i],
+                row[i - 1],
+                row[i],
+            )
+
+    return row[last_index]
+
+
+def _lookup_recommended_rounds(radix: int, ell: int) -> float:
+    last_index = len(ROUND_RADICES) - 1
+
+    if radix <= ROUND_RADICES[0]:
+        return _rounds_for_row(0, ell)
+
+    if radix >= ROUND_RADICES[last_index]:
+        return _rounds_for_row(last_index, ell)
+
+    log_radix = math.log(radix)
+    for i in range(1, last_index + 1):
+        if radix <= ROUND_RADICES[i]:
+            return _interpolate(
+                log_radix,
+                math.log(ROUND_RADICES[i - 1]),
+                math.log(ROUND_RADICES[i]),
+                _rounds_for_row(i - 1, ell),
+                _rounds_for_row(i, ell),
+            )
+
+    return _rounds_for_row(last_index, ell)
+
+
+def calculate_recommended_params(
+    radix: int,
+    word_length: int,
+    security_level: int = 128,
+) -> FastParams:
+    if radix < 4 or radix > 256:
+        raise InvalidParametersError("radix must be between 4 and 256")
+    if word_length < 1:
+        raise InvalidParametersError("word_length must be >= 1")
+
+    sec_level = security_level if security_level != 0 else 128
+
+    w_candidate = math.ceil(math.sqrt(word_length))
+    branch_dist1 = max(min(w_candidate, word_length - 2), 0)
+    branch_dist2 = max(branch_dist1 - 1, 1)
+
+    rounds = _lookup_recommended_rounds(radix, word_length)
+    if rounds < 1.0:
+        rounds = 1.0
+    rounds_u = math.ceil(rounds)
+    num_layers = rounds_u * word_length
+
+    return FastParams(
+        radix=radix,
+        word_length=word_length,
+        sbox_count=SBOX_POOL_SIZE,
+        num_layers=num_layers,
+        branch_dist1=branch_dist1,
+        branch_dist2=branch_dist2,
+        security_level=sec_level,
+    )

fast_cipher/prf.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import struct
+
+from cryptography.hazmat.primitives.ciphers import Cipher
+from cryptography.hazmat.primitives.ciphers.algorithms import AES
+from cryptography.hazmat.primitives.ciphers.modes import ECB
+
+AES_BLOCK_SIZE = 16
+CMAC_RB = 0x87
+
+
+def _left_shift_and_xor(data: bytes, xor_byte: int) -> bytes:
+    result = bytearray(AES_BLOCK_SIZE)
+    carry = 0
+    for i in range(AES_BLOCK_SIZE - 1, -1, -1):
+        result[i] = ((data[i] << 1) | carry) & 0xFF
+        carry = (data[i] >> 7) & 1
+    if (data[0] >> 7) & 1:
+        result[AES_BLOCK_SIZE - 1] ^= xor_byte
+    return bytes(result)
+
+
+def aes_cmac(key: bytes, message: bytes) -> bytes:
+    enc = Cipher(AES(key), ECB()).encryptor()
+
+    L = enc.update(b"\x00" * AES_BLOCK_SIZE)
+    k1 = _left_shift_and_xor(L, CMAC_RB)
+    k2 = _left_shift_and_xor(k1, CMAC_RB)
+
+    msg_len = len(message)
+    block_count = max(1, (msg_len + AES_BLOCK_SIZE - 1) // AES_BLOCK_SIZE)
+    last_block_offset = (block_count - 1) * AES_BLOCK_SIZE
+    has_full_last_block = msg_len > 0 and msg_len % AES_BLOCK_SIZE == 0
+
+    last_block = bytearray(AES_BLOCK_SIZE)
+    if has_full_last_block:
+        for i in range(AES_BLOCK_SIZE):
+            last_block[i] = message[last_block_offset + i] ^ k1[i]
+    else:
+        remaining = msg_len - last_block_offset
+        last_block[:remaining] = message[last_block_offset:]
+        last_block[remaining] = 0x80
+        for i in range(AES_BLOCK_SIZE):
+            last_block[i] ^= k2[i]
+
+    state = bytearray(AES_BLOCK_SIZE)
+    for block_index in range(block_count - 1):
+        offset = block_index * AES_BLOCK_SIZE
+        for i in range(AES_BLOCK_SIZE):
+            state[i] ^= message[offset + i]
+        state[:] = enc.update(state)
+
+    for i in range(AES_BLOCK_SIZE):
+        state[i] ^= last_block[i]
+
+    return enc.update(state)
+
+
+def derive_key(
+    master_key: bytes, input_data: bytes, output_length: int = 32
+) -> bytearray:
+    if len(master_key) not in (16, 24, 32):
+        raise ValueError("Master key must be 16, 24, or 32 bytes")
+    if output_length == 0:
+        raise ValueError("Output length must be > 0")
+
+    output = bytearray(output_length)
+    buffer = bytearray(4 + len(input_data))
+    buffer[4:] = input_data
+
+    bytes_generated = 0
+    counter = 0
+    while bytes_generated < output_length:
+        struct.pack_into(">I", buffer, 0, counter)
+        cmac_output = aes_cmac(master_key, buffer)
+        to_copy = min(output_length - bytes_generated, AES_BLOCK_SIZE)
+        output[bytes_generated : bytes_generated + to_copy] = cmac_output[:to_copy]
+        bytes_generated += to_copy
+        counter += 1
+
+    return output

fast_cipher/prng.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import struct
+
+from cryptography.hazmat.primitives.ciphers import Cipher
+from cryptography.hazmat.primitives.ciphers.algorithms import AES
+from cryptography.hazmat.primitives.ciphers.modes import ECB
+
+AES_BLOCK_SIZE = 16
+
+
+class PrngState:
+    """AES-128 ECB counter-mode PRNG matching C/Zig/JS reference implementations."""
+
+    def __init__(self, key: bytes, nonce: bytes) -> None:
+        self._encryptor = Cipher(AES(key), ECB()).encryptor()
+        self._counter = bytearray(nonce)
+        self._buffer = bytearray(AES_BLOCK_SIZE)
+        self._buffer_pos = AES_BLOCK_SIZE  # force refill on first use
+
+    def _increment_counter(self) -> None:
+        for i in range(AES_BLOCK_SIZE - 1, -1, -1):
+            self._counter[i] = (self._counter[i] + 1) & 0xFF
+            if self._counter[i] != 0:
+                break
+
+    def _encrypt_block(self) -> None:
+        self._buffer[:] = self._encryptor.update(self._counter)
+
+    def get_bytes(self, n: int) -> bytes:
+        output = bytearray(n)
+        offset = 0
+        while offset < n:
+            if self._buffer_pos == AES_BLOCK_SIZE:
+                self._increment_counter()
+                self._encrypt_block()
+                self._buffer_pos = 0
+            chunk = min(n - offset, AES_BLOCK_SIZE - self._buffer_pos)
+            output[offset : offset + chunk] = self._buffer[
+                self._buffer_pos : self._buffer_pos + chunk
+            ]
+            self._buffer_pos += chunk
+            offset += chunk
+        return bytes(output)
+
+    def next_u32(self) -> int:
+        data = self.get_bytes(4)
+        return struct.unpack(">I", data)[0]
+
+    def uniform(self, bound: int) -> int:
+        """Unbiased uniform random in [0, bound) using Lemire's method."""
+        if bound <= 1:
+            return 0
+        threshold = (0x100000000 - bound) % bound
+        while True:
+            r = self.next_u32()
+            product = r * bound
+            low = product & 0xFFFFFFFF
+            if low >= threshold:
+                return product >> 32
+
+
+def split_key_material(
+    key_material: bytes, zeroize_iv_suffix: bool
+) -> tuple[bytes, bytes]:
+    key = key_material[:16]
+    iv = bytearray(key_material[16:32])
+    if zeroize_iv_suffix:
+        iv[AES_BLOCK_SIZE - 1] = 0
+        iv[AES_BLOCK_SIZE - 2] = 0
+    return key, bytes(iv)
+
+
+def generate_sequence(
+    num_layers: int, pool_size: int, key_material: bytes
+) -> list[int]:
+    key, iv = split_key_material(key_material, zeroize_iv_suffix=True)
+    prng = PrngState(key, iv)
+    return [prng.uniform(pool_size) for _ in range(num_layers)]

fast_cipher/sbox.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .prng import PrngState, split_key_material
+
+
+@dataclass
+class SBox:
+    perm: list[int]
+    inv: list[int]
+
+
+def generate_sbox(radix: int, prng: PrngState) -> SBox:
+    perm = list(range(radix))
+    for i in range(radix - 1, 0, -1):
+        j = prng.uniform(i + 1)
+        perm[i], perm[j] = perm[j], perm[i]
+    inv = [0] * radix
+    for i in range(radix):
+        inv[perm[i]] = i
+    return SBox(perm=perm, inv=inv)
+
+
+def generate_sbox_pool(radix: int, count: int, key_material: bytes) -> list[SBox]:
+    key, iv = split_key_material(key_material, zeroize_iv_suffix=False)
+    prng = PrngState(key, iv)
+    return [generate_sbox(radix, prng) for _ in range(count)]