jucrypt 0.3.0__tar.gz → 0.3.2__tar.gz

{jucrypt-0.3.0 → jucrypt-0.3.2}/PKG-INFO

@@ -1,12 +1,13 @@
 Metadata-Version: 2.4
 Name: jucrypt
-Version: 0.3.0
+Version: 0.3.2
 Summary: A Fully Parameterised, Story-Key Driven Experimental SPN Cipher
 Author-email: "I. Nabil" <w3nabil@gmail.com>
 License-Expression: Apache-2.0
 Project-URL: Homepage, https://github.com/w3nabil/jucrypt
 Project-URL: Repository, https://github.com/w3nabil/jucrypt
 Project-URL: Issues, https://github.com/w3nabil/jucrypt/issues
+Project-URL: Changelog, https://github.com/w3nabil/jucrypt/changelog.md
 Keywords: cryptography,symmetric encryption,educational crypto,experimental cipher,story-based key derivation
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
@@ -17,7 +18,7 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Operating System :: OS Independent
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Provides-Extra: experiment

jucrypt-0.3.2/jucrypt/__init__.py

@@ -0,0 +1,8 @@
+from .default_sboxes import SBOX_POOL
+from .storyc import STORYC
+from .story import STORY
+from .story256 import STORY256 
+from .story256c import STORYC256
+
+__all__ = ["SBOX_POOL", "STORYC", "STORY", "STORY256", "STORYC256"]
+__version__= "0.3.2"

{jucrypt-0.3.0 → jucrypt-0.3.2}/jucrypt/default_sboxes.py

@@ -2,8 +2,8 @@
 customju/default_sboxes.py
 ==========================
 Default S-box pool for the STORY cipher.
-Generated by convert_sboxes.py on 2026-02-25 16:37 UTC.
-Source: sboxes.json
+Generated by convert_sboxes.py on 2026-03-15 16:37 UTC.
+Source: lab/sboxes.json (DDT_max = 4, and LAT_max = 16)
 S-boxes: 256  (keys 0..255)
 
 Each entry is a permutation of 0..255 (0-indexed, validated).

{jucrypt-0.3.0 → jucrypt-0.3.2}/jucrypt/story.py

@@ -1,7 +1,7 @@
 # =============================================================================
 #                           STORY cipher by JuCrypt
 #   Path    :   jucrypt/story.py
-#   Version :   v0.3.0
+#   Version :   v0.3.2
 #   Author  :   Nabil
 #   DOI     :   <>
 # =============================================================================
@@ -56,8 +56,8 @@ def _derive_cauchy_matrices() -> List[List[int]]:
             a = _GF[a][2]
         return a
 
-    xs = [pow_alpha(i) for i in range(16)]  # α^0 ..... α^15
-    ys = [pow_alpha(i + 16) for i in range(16)]  # α^16 .... α^31
+    xs = [pow_alpha(i) for i in range(16)]       # α^0  ..... α^15
+    ys = [pow_alpha(i + 16) for i in range(16)]  # α^16 ..... α^31
 
     # Cauchy matrix: all xs distinct, all ys distinct, sets disjoint → invertible
     M = [[gf_inv[xs[i] ^ ys[j]] for j in range(16)] for i in range(16)]
@@ -80,16 +80,35 @@ def _derive_cauchy_matrices() -> List[List[int]]:
                     aug[r][k] ^= _GF[f][aug[col][k]]
     return M
 
+
 _MIX_M = _derive_cauchy_matrices()
 
+
+# Build once at import time alongside _GF and _MIX_M
+def _build_mix_table() -> List[List[List[int]]]:
+    """
+    Precompute MDS contributions:
+    _MIX_T[i][j][v] = GF_mul(MIX_M[i][j], v)
+    So _mix inner loop becomes pure XOR, zero GF mul at runtime.
+    """
+    return [
+        [
+            [_GF[_MIX_M[i][j]][v] for v in range(256)]
+            for j in range(16)
+        ]
+        for i in range(16)
+    ]
+
+
+_MIX_T = _build_mix_table()
+
+
 # Main Story Class
 class STORY:
     # Constants
     BLOCK_SIZE = 16  # 128-bit block
-    KEY_SIZE = 32  # 256-bit derived key
-    ROUNDS_MIN = 8  # Minimum actual rounds (key-derived base)
-    ROUNDS_MAX = 12  # Maximum key-derived base
-    # Actual rounds = key-derived base [8-12] + salt offset [0-3] → [8-15]
+    KEY_SIZE   = 32  # 256-bit derived key
+    ROUNDS     = 5
 
     # S-box cache — shared across all instances
     _SBOXES_CACHE: dict = {}
@@ -104,15 +123,14 @@ class STORY:
                 f"S-box {idx}: not a bijection (not a permutation of 0–255)"
             )
 
-    # S-box loading, checks JSON at first, if present then ignores default, if not then default
-    # We are also planning add a feature where you will be able to generate 256 unique sboxes with lower DDT and LAT as well as json to python pool to speed process.
+    # S-box loading — checks JSON first, falls back to default pool
     @classmethod
     def _load_sboxes(cls) -> dict:
         if cls._SBOXES_CACHE:
             return cls._SBOXES_CACHE
 
-        base = os.path.dirname(__file__)
-        json_path = os.path.join(base, "customju", "sboxes.json")
+        base      = os.path.dirname(__file__)
+        json_path = os.path.join(base, "customju", "sboxes.json") # usually the package lib file if installed via pypi
 
         if os.path.isfile(json_path):
             with open(json_path, "r") as f:
@@ -124,7 +142,7 @@ class STORY:
             return cls._SBOXES_CACHE
 
         try:
-            from jucrypt.default_sboxes import SBOX_POOL
+            from .default_sboxes import SBOX_POOL
         except ImportError:
             raise RuntimeError(
                 "STORY S-box pool not found.\n"
@@ -143,87 +161,60 @@ class STORY:
 
     @staticmethod
     def _derive_master_key(story_bytes: bytes) -> Tuple[bytes, bytes]:
-        """Derive enc_key and mac_key from the story key material (bytes)."""
-        ikm = hashlib.shake_256(story_bytes).digest(STORY.KEY_SIZE)
-        enc_key = hmac.new(ikm, b"enc||story_v1_master", hashlib.sha256).digest()
-        mac_key = hmac.new(ikm, b"mac||story_v1_master", hashlib.sha256).digest()
+        """Derive enc_key and mac_key via HKDF-style SHA256."""
+        prk     = hmac.new(b"story_v1_salt", story_bytes, hashlib.sha256).digest()
+        enc_key = hmac.new(prk, b"enc||story_v1_master\x01", hashlib.sha256).digest()
+        mac_key = hmac.new(prk, b"mac||story_v1_master\x02", hashlib.sha256).digest()
         return enc_key, mac_key
 
     @staticmethod
     def _derive_sbox(master: bytes) -> List[int]:
         """Select one S-box from the pool deterministically from master key."""
         all_sboxes = STORY._load_sboxes()
-        pool_size = len(all_sboxes)
-        threshold = 65536 - (65536 % pool_size)
+        pool_size  = len(all_sboxes)
+        threshold  = 65536 - (65536 % pool_size)
 
         stream = bytearray(hashlib.shake_256(b"story_v1_sbox||" + master).digest(64))
-        pos = 0
+        pos    = 0
 
         while True:
-            # Regenerate stream if exhausted
             if pos + 1 >= len(stream):
                 stream = bytearray(
                     hashlib.shake_256(
-                    b"story_v1_sbox||" + master + pos.to_bytes(4, "big")
+                        b"story_v1_sbox||" + master + pos.to_bytes(4, "big")
                     ).digest(64)
                 )
                 pos = 0
-
-            val = (stream[pos] << 8) | stream[pos + 1]
+            val  = (stream[pos] << 8) | stream[pos + 1]
             pos += 2
-
             if val < threshold:
                 return all_sboxes[val % pool_size]
 
     @staticmethod
-    def _derive_round_count(master: bytes) -> int:
-        span = STORY.ROUNDS_MAX - STORY.ROUNDS_MIN + 1
-        threshold = 256 - (256 % span)
-        stream = bytearray(hashlib.shake_256(b"story_v1_rounds||" + master).digest(32))
-        pos = 0
-
-        while True:
-            if pos >= len(stream):
-                stream = bytearray(
-                    hashlib.shake_256(
-                        b"story_v1_rounds||" + master + pos.to_bytes(4, "big")
-                    ).digest(32)
-                )
-                pos = 0
-            b = stream[pos]
-            pos += 1
-            if b < threshold:
-                return STORY.ROUNDS_MIN + (b % span)
-
-    @staticmethod
-    def _expand_round_keys(master: bytes, count: int) -> List[bytes]:
-        """
-        Generate count round keys from master.
-        Each key is the first 16 bytes BLOCK_SIZE of HMAC-SHA256 output,
-        truncated to match the 128-bit block size."""
-        keys = []
-        for r in range(count):
-            label = b"story_v1_round||" + r.to_bytes(4, "big")
-            rk = hmac.new(master, label, hashlib.sha256).digest()[:STORY.BLOCK_SIZE]
-            keys.append(rk)
-        return keys
+    def _derive_round_keys(master: bytes) -> List[bytes]:
+        """Derive ROUNDS x 16-byte round keys from master key."""
+        return [
+            hashlib.shake_256(
+                b"story_v1_roundkey||" + master + i.to_bytes(4, "big")
+            ).digest(16)
+            for i in range(STORY.ROUNDS)
+        ]
 
     @staticmethod
     def _derive_whitening_key(master: bytes) -> bytes:
-        """Final AddRoundKey whitening key | domain-separated from round keys.
-        Truncated to BLOCK_SIZE 16 bytes from the 32-byte HMAC-SHA256 output."""
-        return hmac.new(master, b"story_v1_whitening||", hashlib.sha256).digest()[:STORY.BLOCK_SIZE]
+        """Final AddRoundKey whitening key — domain-separated from round keys."""
+        return hashlib.shake_256(b"story_v1_whitening||" + master).digest(16)
 
     @staticmethod
     def _derive_perm(master: bytes) -> List[int]:
-        """Key-dependent byte permutation."""
+        """Key-dependent byte permutation via unbiased Fisher-Yates."""
         stream = bytearray(hashlib.shake_256(b"story_v1_perm||" + master).digest(64))
-        pos = 0
-        perm = list(range(16))
+        pos    = 0
+        perm   = list(range(16))
 
         for i in range(15, 0, -1):
-            limit = i + 1
-            threshold = 256 - (256 % limit) 
+            limit     = i + 1
+            threshold = 256 - (256 % limit)
             while True:
                 if pos >= len(stream):
                     stream = bytearray(
@@ -232,71 +223,54 @@ class STORY:
                         ).digest(64)
                     )
                     pos = 0
-                b = stream[pos]
+                b   = stream[pos]
                 pos += 1
                 if b < threshold:
-                    j = b % limit
+                    j                = b % limit
                     perm[i], perm[j] = perm[j], perm[i]
                     break
         return perm
 
-    # SPN primitives — all operate on List[int] state in-place
-    @staticmethod
-    def _sub_bytes(state: List[int], sbox: List[int]) -> None:
-        for i in range(16):
-            state[i] = sbox[state[i]]
-
+    # SPN primitives
     @staticmethod
-    def _permute(state: List[int], perm: List[int]) -> None:
+    def _sub_permute(state: List[int], sbox: List[int], perm: List[int]) -> None:
+        """Read from permuted position, then apply sbox — single pass."""
         tmp = state[:]
         for i in range(16):
-            state[i] = tmp[perm[i]]
+            state[i] = sbox[tmp[perm[i]]]
 
     @staticmethod
     def _mix(state: List[int]) -> None:
-        """Full-State MDS Mix over GF(2^8)."""
+        """Full-state MDS mix over GF(2^8) — zero runtime GF mul via precomputed table."""
         result = [0] * 16
         for i in range(16):
+            t   = _MIX_T[i]
             acc = 0
-            row = _MIX_M[i]
             for j in range(16):
-                acc ^= _GF[row[j]][state[j]]
+                acc ^= t[j][state[j]]
             result[i] = acc
-        for i in range(16):
-            state[i] = result[i]
+        state[:] = result
 
-    # Block encryption, pure bytes to speed up the process
+    # Block encryption
     @staticmethod
     def _encrypt_block(
-        block: bytes,
-        perm: List[int],
-        sbox: List[int],
-        round_keys: List[bytes],
-        final_key: bytes,
+        block      : bytes,
+        sbox       : List[int],
+        perm       : List[int],
+        round_keys : List[bytes],
+        final_int  : int,
     ) -> bytes:
         """Encrypt one 16-byte block."""
         state = list(block)
-
         for rk in round_keys:
             for i in range(16):
                 state[i] ^= rk[i]
-            STORY._sub_bytes(state, sbox)
-            STORY._permute(state, perm)
+            STORY._sub_permute(state, sbox, perm)
             STORY._mix(state)
+        # Final whitening — single int XOR, no loop
+        return (int.from_bytes(bytes(state), "big") ^ final_int).to_bytes(16, "big")
 
-        # Final whitening, closes the last Mix against key-recovery
-        for i in range(16):
-            state[i] ^= final_key[i]
-
-        return bytes(state)
-
-    # Counter block
-    @staticmethod
-    def _make_counter_block(nonce: bytes, counter: int) -> bytes:
-        """8-byte nonce || 8-byte big-endian counter → 16-byte block."""
-        return nonce + counter.to_bytes(8, "big")
-
-    # Input normalisation, preinstalled for software needs with less code.
+    # Input normalisation
     @staticmethod
     def _to_bytes(data) -> bytes:
         """Convert any supported plaintext type to bytes."""
@@ -307,13 +281,12 @@ class STORY:
         if isinstance(data, str):
             return data.encode("utf-16-le")
         raise TypeError(
-            f"Plaintext must be str, bytes, or bytearray."
-            f"Got: {type(data).__name__}"
+            f"Plaintext must be str, bytes, or bytearray. Got: {type(data).__name__}"
         )
 
     @staticmethod
     def _to_bytes_param(data, name: str) -> bytes:
-        """Convert a hex string or bytes parameter (nonce / tag / round_salt)."""
+        """Convert a hex string or bytes parameter (nonce / tag)."""
         if isinstance(data, (bytes, bytearray)):
             return bytes(data)
         if isinstance(data, str):
@@ -327,118 +300,113 @@ class STORY:
 
     # Public API
     @staticmethod
-    def encrypt(plaintext, story: str) -> Tuple[str, str, str, str]:
-        """Encrypt plaintext under a story key."""
-        pt_bytes = STORY._to_bytes(plaintext)
-        story_norm = unicodedata.normalize("NFC", story)
-        story_bytes = story_norm.encode("utf-16-le") 
-        enc_key, mac_key = STORY._derive_master_key(story_bytes)
-        sbox = STORY._derive_sbox(enc_key)
-        perm = STORY._derive_perm(enc_key)
-        base_rounds = STORY._derive_round_count(enc_key)  
+    def encrypt(plaintext, story: str) -> Tuple[bytes, bytes, bytes]:
+        """Encrypt plaintext under a story key.
+
+        Returns (ciphertext, nonce, tag) all as bytes.
+        """
+        pt_bytes    = STORY._to_bytes(plaintext)
+        story_norm  = unicodedata.normalize("NFC", story)
+        story_bytes = story_norm.encode("utf-16-le")
 
-        round_salt = os.urandom(1)
-        salt_offset = round_salt[0] % 4  
-        actual_rounds = base_rounds + salt_offset 
+        enc_key, mac_key = STORY._derive_master_key(story_bytes)
 
-        round_keys = STORY._expand_round_keys(enc_key, actual_rounds)
-        final_key = STORY._derive_whitening_key(enc_key) 
+        # Key schedule — paid once per message
+        sbox       = STORY._derive_sbox(enc_key)
+        perm       = STORY._derive_perm(enc_key)
+        round_keys = STORY._derive_round_keys(enc_key)
+        final_key  = STORY._derive_whitening_key(enc_key)
+        final_int  = int.from_bytes(final_key, "big")  # precomputed once
 
         # CTR encryption
-        nonce = os.urandom(8)
+        nonce      = os.urandom(8)
         ciphertext = bytearray()
-        counter = 0
+        counter    = 0
 
         for i in range(0, len(pt_bytes), STORY.BLOCK_SIZE):
-            block = pt_bytes[i : i + STORY.BLOCK_SIZE]
+            block     = pt_bytes[i : i + STORY.BLOCK_SIZE]
             keystream = STORY._encrypt_block(
-                STORY._make_counter_block(nonce, counter),
-                perm,
+                nonce + counter.to_bytes(8, "big"),
                 sbox,
+                perm,
                 round_keys,
-                final_key,
+                final_int,
             )
-            ciphertext.extend(b ^ k for b, k in zip(block, keystream))
+            # zip handles last partial block naturally — no padding needed in CTR
+            ciphertext.extend(ks ^ pb for ks, pb in zip(keystream, block))
             counter += 1
 
-        # Authenticate: HMAC over nonce || round_salt || ciphertext
+        # Authenticate: HMAC-SHA256 over nonce || ciphertext
         tag = hmac.new(
             mac_key,
-            nonce + round_salt + bytes(ciphertext),
+            nonce + bytes(ciphertext),
             hashlib.sha256,
         ).digest()
 
-        return (
-            bytes(ciphertext),
-            nonce,
-            tag,
-            round_salt,
-        )
+        return bytes(ciphertext), nonce, tag
 
     @staticmethod
     def decrypt(
-        ciphertext: Union[str, bytes],
-        story: str,
-        nonce: Union[str, bytes],
-        tag: Union[str, bytes],
-        round_salt: Union[str, bytes],
+        ciphertext : Union[str, bytes],
+        story      : str,
+        nonce      : Union[str, bytes],
+        tag        : Union[str, bytes],
     ) -> bytes:
         """Decrypt and authenticate a STORY ciphertext."""
-        ct_bytes = STORY._to_bytes_param(ciphertext, "ciphertext")
-        nc_bytes = STORY._to_bytes_param(nonce, "nonce")
-        tag_bytes = STORY._to_bytes_param(tag, "tag")
-        rs_bytes = STORY._to_bytes_param(round_salt, "round_salt")
-        story_norm = unicodedata.normalize("NFC", story)
+        ct_bytes  = STORY._to_bytes_param(ciphertext, "ciphertext")
+        nc_bytes  = STORY._to_bytes_param(nonce,      "nonce")
+        tag_bytes = STORY._to_bytes_param(tag,        "tag")
+
+        story_norm  = unicodedata.normalize("NFC", story)
         story_bytes = story_norm.encode("utf-16-le")
+
         enc_key, mac_key = STORY._derive_master_key(story_bytes)
-        sbox = STORY._derive_sbox(enc_key)
-        perm = STORY._derive_perm(enc_key)
-        base_rounds = STORY._derive_round_count(enc_key)
-        salt_offset = rs_bytes[0] % 4
-        actual_rounds = base_rounds + salt_offset
 
-        round_keys = STORY._expand_round_keys(enc_key, actual_rounds)
-        final_key = STORY._derive_whitening_key(enc_key)
+        # Key schedule — paid once per message
+        sbox       = STORY._derive_sbox(enc_key)
+        perm       = STORY._derive_perm(enc_key)
+        round_keys = STORY._derive_round_keys(enc_key)
+        final_key  = STORY._derive_whitening_key(enc_key)
+        final_int  = int.from_bytes(final_key, "big")  # precomputed once
 
-        # Authenticate
+        # Authenticate first — fail fast before any decryption
         check = hmac.new(
             mac_key,
-            nc_bytes + rs_bytes + ct_bytes,
+            nc_bytes + ct_bytes,
             hashlib.sha256,
         ).digest()
         if not hmac.compare_digest(check, tag_bytes):
             raise ValueError(
                 "Authentication Failed.\n"
-                "The ciphertext, nonce, tag, or round_salt has been tampered with,\n"
+                "The ciphertext, nonce, or tag has been tampered with,\n"
                 "or the story key is incorrect."
             )
-
         # CTR decryption
         plaintext = bytearray()
-        counter = 0
+        counter   = 0
 
         for i in range(0, len(ct_bytes), STORY.BLOCK_SIZE):
-            block = ct_bytes[i : i + STORY.BLOCK_SIZE]
+            block     = ct_bytes[i : i + STORY.BLOCK_SIZE]
             keystream = STORY._encrypt_block(
-                STORY._make_counter_block(nc_bytes, counter),
-                perm,
+                nc_bytes + counter.to_bytes(8, "big"),
                 sbox,
+                perm,
                 round_keys,
-                final_key,
+                final_int,
             )
-            plaintext.extend(b ^ k for b, k in zip(block, keystream))
+            # zip handles last partial block naturally — no padding needed in CTR
+            plaintext.extend(ks ^ cb for ks, cb in zip(keystream, block))
             counter += 1
 
         return bytes(plaintext)
 
     @staticmethod
     def decrypt_str(
-        ciphertext: Union[str, bytes],
-        story: str,
-        nonce: Union[str, bytes],
-        tag: Union[str, bytes],
-        round_salt: Union[str, bytes],
-        encoding: str = "utf-16-le",
+        ciphertext : Union[str, bytes],
+        story      : str,
+        nonce      : Union[str, bytes],
+        tag        : Union[str, bytes],
+        encoding   : str = "utf-16-le",
     ) -> str:
         """Decrypt and decode to string. Default encoding is UTF-16-LE."""
-        return STORY.decrypt(ciphertext, story, nonce, tag, round_salt).decode(encoding)
+        return STORY.decrypt(ciphertext, story, nonce, tag).decode(encoding)