A full-source, evidence-first engine for educational cryptanalysis of classical ciphers. v10.1 is designed to work from ciphertext alone: the normal solver API does not require a known plaintext or secret key.
The project supports Caesar, Affine, Vigenère, general monoalphabetic substitution, and Playfair 5×5. Small keyspaces are searched exhaustively; larger keyspaces use statistical or stochastic search with explicit confidence evidence rather than an unexplained single guess.
The diagram below summarizes the end-to-end UCE v10.1 workflow, from interactive user input through cipher-family routing, specialized cryptanalysis modules, shared scoring and validation services, and finally structured analysis results.
The architecture is intentionally modular: cipher-specific solvers are isolated from shared language scoring, canonical-key handling, validation, readability post-processing, and reporting. This keeps ciphertext-only analysis transparent and makes individual components easier to test and extend.
- Restores the complete advanced controls from the v9 line while keeping the cleaner v10 architecture.
- Adds explicit general substitution routing to the public API and CLI.
- Restores configurable
top_kandmax_vigenere_key_len. - Exposes substitution restarts/iterations and the Playfair backend.
- Adds
run_self_test()for a one-command engine health check. - Marks results explicitly as ciphertext-only and reports whether known plaintext was used.
- Keeps Playfair independent-run consensus and deterministic canonical equivalent key-squares.
- Ships a full-source notebook: no Base64-packed engine blob. Every core module is visible and reviewable inside the notebook.
- Removes task-specific seed words from the Playfair initialization path.
Yes, depending on the cipher and the amount/quality of ciphertext:
| Cipher | Ciphertext-only key recovery | Method |
|---|---|---|
| Caesar | Deterministic | Exhaustive 26-shift search |
| Affine | Deterministic | Exhaustive valid (a,b) search |
| Vigenère | Statistical | IC/Kasiski + column shift recovery + language ranking |
| General substitution | Heuristic | Simulated annealing + n-gram scoring |
| Playfair | Heuristic | Simulated annealing + n-gram scoring + independent-run consensus |
For Playfair, the engine can recover a square that decrypts the ciphertext correctly without being given the plaintext. However, the original human-entered keyword is generally not uniquely identifiable from ciphertext alone. Equivalent 5×5 squares can implement the same Playfair transformation, so the engine reports a Canonical Equivalent Playfair Key-Square.
python -m pip install -r requirements-accelerated.txtIf Numba is unavailable:
python -m pip install -r requirements.txtpython run_engine.pyThe default interaction is intentionally simple:
Paste ciphertext: <paste here>
The engine continues automatically and prints the detected family, language, confidence, recovered key/key-square, validation evidence, and plaintext.
from uce import run_engine
run_engine(advanced=True)Advanced mode exposes:
- language:
auto | english | indonesian - cipher:
auto | playfair | caesar | affine | vigenere | substitution - search depth:
fast | balanced | deep - independent validation runs
- random seed
- top-k candidate count
- maximum Vigenère key length
- substitution restarts and iterations
- Playfair backend:
auto | numba | numpy
from uce import solve
from uce.reporting import format_result
result = solve(
ciphertext,
language="auto",
cipher_hint="auto",
)
print(format_result(result))Playfair ciphertext-only recovery:
result = solve(
ciphertext,
language="auto",
cipher_hint="playfair",
mode="deep",
validation_runs=5,
seed=2026,
top_k=8,
playfair_backend="auto",
)General substitution:
result = solve(
ciphertext,
language="english",
cipher_hint="substitution",
substitution_restarts=12,
substitution_iterations=10000,
)Playfair has a huge keyspace. A single stochastic result is not labeled as proof. v10.1 separates:
- Self-consistency: candidate square decrypts and re-encrypts consistently.
- Independent-run plaintext agreement: separate searches converge on the same plaintext.
- Equivalent-key agreement: recovered squares belong to the same standard Playfair equivalence class.
- Language score: the result is plausible under the selected language model.
HIGH confidence requires multiple independent searches to agree under the validation rules. This is strong cryptanalytic evidence, not proof of the sender's original keyword phrase.
Use:
notebooks/Universal_Cryptanalysis_Engine_v10.1_Professional_Full_Source.ipynb
The notebook writes the visible module cells to a local uce/ package, runs run_self_test(), and then provides an interactive run_engine() cell. It is intentionally larger than the compressed v10.0 standalone notebook because the source is readable rather than hidden inside a Base64 archive.
from uce import run_self_test
run_self_test()The deterministic health check covers Caesar, Affine, Vigenère, substitution primitives, the Playfair course vector, Playfair equivalent-square canonicalization, solver recovery, and ciphertext-only evidence semantics.
For the full regression suite:
python -m pytest -q.
├── README.md
├── LICENSE
├── pyproject.toml
├── requirements.txt
├── requirements-accelerated.txt
├── requirements-dev.txt
├── run_engine.py
├── uce/
│ ├── __init__.py
│ ├── classical.py
│ ├── playfair.py
│ ├── validation.py
│ ├── readability.py
│ ├── engine.py
│ ├── reporting.py
│ ├── cli.py
│ └── selftest.py
├── notebooks/
│ └── Universal_Cryptanalysis_Engine_v10.1_Professional_Full_Source.ipynb
├── examples/
├── docs/
└── tests/
This project is for classical-cryptography education, coursework, CTF-style exercises, reproducible cryptanalysis experiments, and historical cipher research. It is not a modern cryptographic security library.
MIT.