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
```
