jucrypt 0.4.0

The parent dir of STORY, MUCRYPT, RESIMAGE and many more...

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 before use.

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:

{
  "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

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