jucrypt 0.3.2__tar.gz → 0.4.0__tar.gz

jucrypt-0.4.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: jucrypt
+Version: 0.4.0
+Summary: The parent dir of STORY, MUCRYPT, RESIMAGE and many more...
+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
+Classifier: Intended Audience :: Education
+Classifier: Topic :: Security :: Cryptography
+Classifier: Programming Language :: Python :: 3
+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.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: experiment
+Requires-Dist: numpy>=1.23; extra == "experiment"
+Requires-Dist: scipy>=1.17.1; extra == "experiment"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# Ju's Story (STORY)
+
+> **Your story is your key.**
+> A story-key driven Substitution-Permutation Network cipher.
+
+> **Pre-review research cipher.** No external cryptanalysis or formal peer review has been conducted yet. We are actively seeking feedback from the research community. See [Current Limitations and Open Issues](#current-limitations-and-open-issues) before use.
+
+[![Python](https://img.shields.io/badge/Python-3.9%2B-blue?logo=python)](https://www.python.org/)
+[![License](https://img.shields.io/badge/Apace-2.0-green)](LICENSE)
+[![PyPI](https://img.shields.io/badge/PyPI-jucrypt-orange?logo=pypi)](https://pypi.org/project/jucrypt/)
+
+STORY is an experimental symmetric block cipher in which the secret key is a natural-language narrative — a sentence, a paragraph, or any Unicode text — rather than a raw byte string. It operates on 128-bit blocks using a Substitution-Permutation Network (SPN), and provides authenticated encryption through CTR mode combined with HMAC-SHA-256 in an Encrypt-then-MAC construction. Please consider reading our paper bearing doi 10.31224/6477 before testing or using our STORY2.
+
+The project is published as `jucrypt` on PyPI. The cipher, key derivation pipeline, and test suite are entirely open. We are conducting empirical security testing and would genuinely appreciate researchers using, testing, and critiquing the design.
+
+---
+
+## Current Limitations and Open Issues
+
+We are disclosing all known issues in full. This is a pre-review cipher and transparency is more useful to the community than silence.
+
+**Issue 1 — No formal peer review**
+
+The cipher design, key derivation pipeline, and all empirical results above have not undergone external cryptanalysis or formal peer review. STORY should be treated as a research prototype. We are actively seeking differential, linear, algebraic, and structural cryptanalysis. If you attempt an attack, successful or not, we would like to hear about it.
+
+**Issue 2 — IND-CPA composite pass rate of 97.7%**
+
+The individual IND-CPA sub-tests (semantic security, length leakage, prefix indistinguishability) all pass at 100%. The composite failure originates in the statistical distribution test (98.8%) and the key-change test (99.0%). Approximately 1% false failures are expected under α = 0.01, but the remaining ~1.3% excess is currently under investigation. No confirmed root cause has been identified yet.
+
+**Issue 3 — SAC measurement error in test suite prior to v4.2.0**
+
+In `story_basic.py` versions prior to v4.2.0, the `sac_avg` column was numerically identical to `avalanche_pct / 100` — a redundant column carrying no independent information. The SAC figures in CSV files up to `story_basic_7.csv` should be read as a restatement of the avalanche figure, not an independent measurement. Fixed in v4.2.0, which now reports genuine per-output-bit SAC variance (`sac_std`, `sac_min_bit`, `sac_max_bit`).
+
+**Issue 4 — BIC implementation error in test suite prior to v4.2.0**
+
+The `_bic()` function in `story_deep.py` prior to v4.2.0 measured per-input-bit avalanche rate rather than the pairwise output-bit independence criterion defined by Webster and Tavares (1986). The BIC columns in `story_deep` CSV files prior to v4.2.0 are mislabelled and should be disregarded. Fixed in v4.2.0, which now computes Pearson correlation across all C(128, 2) = 8,128 output-bit pairs.
+
+**Issue 5 — Variable round count increases timing variance**
+
+Actual rounds per message vary from 8 to 15. This is intentional — it adds per-message variability — but it causes higher coefficient of variation in timing measurements than a fixed-round cipher would produce. The API does not currently expose a fixed-round mode, so timing benchmarks reflect an average over the round-count distribution.
+
+**Issue 6 — C extension requires manual compilation**
+
+The `story_core.c` extension provides roughly 10× throughput improvement but must be compiled manually. A pip-installable binary wheel is not yet available. The pure-Python fallback is automatic.
+
+**Issue 7 — No custom S-box generation tooling yet**
+
+A tool to generate validated custom S-box pools with verified DDT and LAT properties is planned but not yet released.
+
+---
+
+## Custom S-box Pool
+
+STORY supports user-supplied S-boxes. If a file exists at `customju/sboxes.json` relative to `story.py`, it takes precedence over the default pool. Format:
+
+```json
+{
+  "0": "1,200,87,...",
+  "1": "43,11,..."
+}
+```
+
+Each value is a comma-separated list of 256 integers forming a bijection of 0–255. Values are stored 1-indexed in the JSON (add 1 to each actual S-box value when writing). The loader validates each entry as a permutation of 0–255 and raises `ValueError` if the check fails.
+
+Any custom pool should be validated for DDT max ≤ 4 and NL ≥ 112 before deployment. Pools with weaker properties will reduce the security margins reported in the test results above.
+
+---
+
+## For Researchers
+
+**Source files**
+
+| File | Contents |
+|---|---|
+| `story.py`            | Pure-Python reference implementation, fully commented |
+| `story2.py`            | Pure-Python reference implementation, fully commented, no shiftrow and premute|
+| `storyc.py`           | C-accelerated variant and CLI |
+| `story_core.c`        | C extension: GF(2⁸) multiply table, MDS Mix, CTR-mode kernel |
+| `default_sboxes.py`   | S-BOX Pool file |
+
+**Reproducing the test results**
+
+```bash
+git clone https://github.com/w3nabil/jucrypt
+cd jucrypt/analyse
+pip install numpy scipy pulp
+python story2_basic.py --workers 4
+python story2_formal.py --quick
+```
+
+**Attack surfaces we have not fully explored**
+
+- Algebraic attacks exploiting the HMAC-based key schedule structure
+- Related-story attacks (stories differing by a single character or punctuation mark)
+- Timing side-channels in the pure-Python execution path
+- The confirmed root cause of the 2.3% IND-CPA composite failure
+- Invariant subspace attacks using the full round function under key-derived parameters
+
+If you find a weakness — or confirm the absence of one — please open an issue or contact us directly. We would rather know.
+
+---
+
+## Citation
+
+If you reference STORY2 or STORY in research, please cite:
+
+```
+Islam, N. (2026). STORY2: A Fully Parameterised, Story-Key Driven SPN Cipher.
+DOI: 10.31224/6477
+```

jucrypt-0.4.0/README.md

@@ -0,0 +1,110 @@
+# Ju's Story (STORY)
+
+> **Your story is your key.**
+> A story-key driven Substitution-Permutation Network cipher.
+
+> **Pre-review research cipher.** No external cryptanalysis or formal peer review has been conducted yet. We are actively seeking feedback from the research community. See [Current Limitations and Open Issues](#current-limitations-and-open-issues) before use.
+
+[![Python](https://img.shields.io/badge/Python-3.9%2B-blue?logo=python)](https://www.python.org/)
+[![License](https://img.shields.io/badge/Apace-2.0-green)](LICENSE)
+[![PyPI](https://img.shields.io/badge/PyPI-jucrypt-orange?logo=pypi)](https://pypi.org/project/jucrypt/)
+
+STORY is an experimental symmetric block cipher in which the secret key is a natural-language narrative — a sentence, a paragraph, or any Unicode text — rather than a raw byte string. It operates on 128-bit blocks using a Substitution-Permutation Network (SPN), and provides authenticated encryption through CTR mode combined with HMAC-SHA-256 in an Encrypt-then-MAC construction. Please consider reading our paper bearing doi 10.31224/6477 before testing or using our STORY2.
+
+The project is published as `jucrypt` on PyPI. The cipher, key derivation pipeline, and test suite are entirely open. We are conducting empirical security testing and would genuinely appreciate researchers using, testing, and critiquing the design.
+
+---
+
+## Current Limitations and Open Issues
+
+We are disclosing all known issues in full. This is a pre-review cipher and transparency is more useful to the community than silence.
+
+**Issue 1 — No formal peer review**
+
+The cipher design, key derivation pipeline, and all empirical results above have not undergone external cryptanalysis or formal peer review. STORY should be treated as a research prototype. We are actively seeking differential, linear, algebraic, and structural cryptanalysis. If you attempt an attack, successful or not, we would like to hear about it.
+
+**Issue 2 — IND-CPA composite pass rate of 97.7%**
+
+The individual IND-CPA sub-tests (semantic security, length leakage, prefix indistinguishability) all pass at 100%. The composite failure originates in the statistical distribution test (98.8%) and the key-change test (99.0%). Approximately 1% false failures are expected under α = 0.01, but the remaining ~1.3% excess is currently under investigation. No confirmed root cause has been identified yet.
+
+**Issue 3 — SAC measurement error in test suite prior to v4.2.0**
+
+In `story_basic.py` versions prior to v4.2.0, the `sac_avg` column was numerically identical to `avalanche_pct / 100` — a redundant column carrying no independent information. The SAC figures in CSV files up to `story_basic_7.csv` should be read as a restatement of the avalanche figure, not an independent measurement. Fixed in v4.2.0, which now reports genuine per-output-bit SAC variance (`sac_std`, `sac_min_bit`, `sac_max_bit`).
+
+**Issue 4 — BIC implementation error in test suite prior to v4.2.0**
+
+The `_bic()` function in `story_deep.py` prior to v4.2.0 measured per-input-bit avalanche rate rather than the pairwise output-bit independence criterion defined by Webster and Tavares (1986). The BIC columns in `story_deep` CSV files prior to v4.2.0 are mislabelled and should be disregarded. Fixed in v4.2.0, which now computes Pearson correlation across all C(128, 2) = 8,128 output-bit pairs.
+
+**Issue 5 — Variable round count increases timing variance**
+
+Actual rounds per message vary from 8 to 15. This is intentional — it adds per-message variability — but it causes higher coefficient of variation in timing measurements than a fixed-round cipher would produce. The API does not currently expose a fixed-round mode, so timing benchmarks reflect an average over the round-count distribution.
+
+**Issue 6 — C extension requires manual compilation**
+
+The `story_core.c` extension provides roughly 10× throughput improvement but must be compiled manually. A pip-installable binary wheel is not yet available. The pure-Python fallback is automatic.
+
+**Issue 7 — No custom S-box generation tooling yet**
+
+A tool to generate validated custom S-box pools with verified DDT and LAT properties is planned but not yet released.
+
+---
+
+## Custom S-box Pool
+
+STORY supports user-supplied S-boxes. If a file exists at `customju/sboxes.json` relative to `story.py`, it takes precedence over the default pool. Format:
+
+```json
+{
+  "0": "1,200,87,...",
+  "1": "43,11,..."
+}
+```
+
+Each value is a comma-separated list of 256 integers forming a bijection of 0–255. Values are stored 1-indexed in the JSON (add 1 to each actual S-box value when writing). The loader validates each entry as a permutation of 0–255 and raises `ValueError` if the check fails.
+
+Any custom pool should be validated for DDT max ≤ 4 and NL ≥ 112 before deployment. Pools with weaker properties will reduce the security margins reported in the test results above.
+
+---
+
+## For Researchers
+
+**Source files**
+
+| File | Contents |
+|---|---|
+| `story.py`            | Pure-Python reference implementation, fully commented |
+| `story2.py`            | Pure-Python reference implementation, fully commented, no shiftrow and premute|
+| `storyc.py`           | C-accelerated variant and CLI |
+| `story_core.c`        | C extension: GF(2⁸) multiply table, MDS Mix, CTR-mode kernel |
+| `default_sboxes.py`   | S-BOX Pool file |
+
+**Reproducing the test results**
+
+```bash
+git clone https://github.com/w3nabil/jucrypt
+cd jucrypt/analyse
+pip install numpy scipy pulp
+python story2_basic.py --workers 4
+python story2_formal.py --quick
+```
+
+**Attack surfaces we have not fully explored**
+
+- Algebraic attacks exploiting the HMAC-based key schedule structure
+- Related-story attacks (stories differing by a single character or punctuation mark)
+- Timing side-channels in the pure-Python execution path
+- The confirmed root cause of the 2.3% IND-CPA composite failure
+- Invariant subspace attacks using the full round function under key-derived parameters
+
+If you find a weakness — or confirm the absence of one — please open an issue or contact us directly. We would rather know.
+
+---
+
+## Citation
+
+If you reference STORY2 or STORY in research, please cite:
+
+```
+Islam, N. (2026). STORY2: A Fully Parameterised, Story-Key Driven SPN Cipher.
+DOI: 10.31224/6477
+```

{jucrypt-0.3.2 → jucrypt-0.4.0}/jucrypt/__init__.py

@@ -3,6 +3,7 @@ from .storyc import STORYC
 from .story import STORY
 from .story256 import STORY256 
 from .story256c import STORYC256
+from .story2 import STORY2
 
-__all__ = ["SBOX_POOL", "STORYC", "STORY", "STORY256", "STORYC256"]
-__version__= "0.3.2"
+__all__ = ["SBOX_POOL", "STORYC", "STORY", "STORY256", "STORYC256", "STORY2"]
+__version__= "0.4.0"