# ChaosCrypt **A chaos-based obfuscation cipher with a self-describing format, four performance modes, a bilingual TUI, a full CLI, and a clean Python API.** [![Python](https://img.shields.io/badge/python-3.8%2B-blue)](https://www.python.org/) [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE) [![Dependencies](https://img.shields.io/badge/dependencies-none-brightgreen)](#installation) --- ## Scope ChaosCrypt is an **unaudited, non-standardised** cipher. It is built for three purposes: | | Purpose | What it means in practice | |---|---|---| | 1 | **Obfuscation** | Making data unreadable to casual inspection | | 2 | **Personal use** | Protecting your own notes, journals and backups | | 3 | **Research & teaching** | Studying how layered obfuscation behaves | **If you need standardised cryptography, use a standardised cipher.** AES-GCM or ChaCha20-Poly1305 from a vetted library such as [`cryptography`](https://cryptography.io) are the right tools for production systems, regulated data, and long-lived secrets. See [SECURITY.md](SECURITY.md) for the full design and threat analysis, and [docs/FORMAT.md](docs/FORMAT.md) for the normative format specification. --- ## Every artefact describes itself Each key file and ciphertext begins with a header that states how it was made. A reader never has to be told the mode, the encoding, or anything else — it reads them from the artefact. ``` 69CES 385aeff1f4179a744c8fb0c5ae4702d325f6230d059f4251135c2536409dee93 {"alg":"chaoscrypt","kind":"ciphertext","mode":"turbo","out":"hex","mid":"bt",...} 2025ea4e4b4b93803f2ccadeaf318d1957ce42ff5409410f660348be96a4c0f2 ``` The consequence is deliberate: **input without a valid header is rejected** (`E017`), rather than guessed at. A ciphertext decrypted under the wrong parameters produces garbage that looks like a wrong password, and the header removes that ambiguity entirely. ```python from chaoscrypt import ChaosCrypt cc = ChaosCrypt(key_file="my.key", key_password="key-file-password", auto_load=True) # whatever produced this, it will be read correctly plain = cc.decrypt(open("message.ces").read(), "encryption-password") ``` --- ## Performance modes Four modes, selectable at construction, on the command line, and from the TUI. | Mode | Algorithm | Ciphertext | Compatible with pre-4.2.6 material | |---|---|---|---| | `reference` | the original algorithm, character pipeline | 5.33x | payload identical | | `fast` *(default)* | same algorithm, bulk operations | 5.33x | payload identical | | `turbo` | SHAKE256 keystream, byte pipeline | 2.00x / 1.33x | no | | `raw` | SHAKE256 plus the long-key layer | 2.00x / 1.33x | no | `turbo` and `raw` take two extra settings: | Setting | Values | Meaning | |---|---|---| | `encoding` | `hex` (default), `base64` | final output encoding: 2.00x or 1.33x expansion | | `mid` | `bt` (default), `hex` | whether bytes or hexadecimal text are carried between the XOR layers | ```python from chaoscrypt import ChaosCrypt cc = ChaosCrypt(mode="raw", encoding="base64", mid="bt") ``` ```bash chaoscrypt encrypt "hello" -p pw -k my.key -P kp --mode raw --encoding base64 ``` ### Measured throughput Hex output, `raw` mode, 1 MiB payloads and above: | mid | Encrypt | Decrypt | Ciphertext | |---|---:|---:|---:| | `bt` (default) | **57–63 MB/s** | **61–73 MB/s** | 2.00x | | `hex` | 18–21 MB/s | 18–23 MB/s | 8.00x | Throughput holds steady from 64 KiB to 1 GiB, which is what a linear algorithm looks like. Full figures, including the profiling behind them, are in [docs/benchmark.md](docs/benchmark.md). For scale: the original implementation managed **0.08 MB/s**, about twelve seconds per megabyte. --- ## Reading artefacts from before 4.2.6 Artefacts written before the header existed have none. They are read through a compatibility API, which synthesises a minimal header and then uses the ordinary path — so the strict path stays strict, and there is no lenient branch inside it. ```python from chaoscrypt import ChaosCrypt cc = ChaosCrypt(key_file="my.key", key_password="key-file-password", auto_load=True) # a ciphertext with no header plain = cc.decrypt_legacy("72370655031311011c111f261365172716020b69", "encryption-password") # a key file with no header cc.load_legacy_keys(open("old.key", encoding="utf-8").read(), "key-password") # or modernise one, once open("new.key", "w", encoding="utf-8").write( cc.wrap_legacy(open("old.key", encoding="utf-8").read(), is_key=True) ) ``` `decrypt_legacy_auto` probes whether the artefact is a key file or a ciphertext, so the caller does not have to know. See [docs/FORMAT.md §12](docs/FORMAT.md) for the legacy standard. --- ## Installation ```bash pip install chaoscrypt ``` **Requires** Python 3.8 or newer. No third-party runtime dependencies. --- ## Three ways to use it ### 1. As a library ```python from chaoscrypt import ChaosCrypt cc = ChaosCrypt() cc.create_key("key-file-password", "my.key") token = cc.encrypt("hello world", "encryption-password") assert cc.decrypt(token, "encryption-password") == "hello world" ``` Binary data and files: ```python cc = ChaosCrypt("my.key", "key-file-password", auto_load=True) raw = open("photo.png", "rb").read() open("photo.cc", "w").write(cc.encrypt_bytes(raw, "encryption-password")) cc.encrypt_file("photo.png", "encryption-password") # -> photo.png.cc cc.decrypt_file("photo.png.cc", "encryption-password") # -> photo.png ``` Error handling — every failure is a `ChaosCryptError` and renders as `ChaosCrypt_ERR__`: ```python from chaoscrypt import ChaosCrypt, ChaosCryptError try: ChaosCrypt().load("my.key", "wrong-password") except ChaosCryptError as e: print(e) # ChaosCrypt_ERR_KeyPasswordIncorrect_E003 print(e.code) # E003 ``` ### 2. As a command line tool **No arguments** launches the interactive TUI. **With arguments** it is a scriptable CLI: ```bash chaoscrypt keygen -k my.key --key-pwd-env KEY_PWD chaoscrypt encrypt "hello world" -p mypass -k my.key -P keypass chaoscrypt decrypt "1a2b3c..." -p mypass -k my.key -P keypass chaoscrypt file encrypt photo.png -p mypass -k my.key -P keypass chaoscrypt info -k my.key -P keypass --json chaoscrypt chpwd -k my.key -P oldpass --new-pwd newpass ``` `-p`/`--pwd` is the **encryption password**; `-P`/`--key-pwd` is the **key file password**. Passwords may come inline, from an environment variable, or from a file. **Exit codes:** `0` success, `1` runtime error, `2` usage error. See [docs/CLI.md](docs/CLI.md) for the full reference. ### 3. As an interactive TUI ```bash chaoscrypt ``` ``` +================================================================+ | ChaosCrypt - Chaos Obfuscation Cipher v4.2.6 | +================================================================+ [*] Key file loaded my.key [fast] ------------------------------------------------------------------ Select an action ------------------------------------------------------------------ [1] Encrypt text [2] Decrypt text [3] Encrypt file [4] Decrypt file [5] Generate a new key file [6] Load a key file [7] Show key information [8] Change key file password [9] Switch language [m] Performance mode [e] Output encoding [a] About / security notice [q] Quit ------------------------------------------------------------------ ``` Bilingual (option `[9]`), passwords are not echoed, and the interface degrades cleanly when output is piped. --- ## Error codes | Code | Meaning | |---|---| | `E001` | Key file not found | | `E002` | Key file corrupted | | `E003` | Key file password incorrect | | `E004` | No key loaded | | `E005` | Key file already exists | | `E006` | A required password was missing | | `E007` | Password mismatch | | `E008` | Empty plaintext | | `E009` | Empty ciphertext | | `E010` | Malformed payload (not valid hexadecimal, or bad length) | | `E011` | Decryption failed (wrong password, wrong key, or tampered) | | `E012` | Encoding failure | | `E013` | Invalid argument | | `E014` | File read failed | | `E015` | File write failed | | `E016` | Unsupported key file version | | `E017` | **Missing magic header** — not a CES artefact | | `E018` | **Malformed header** — marker missing, JSON unusable, or `kind` mismatch | Codes are stable and safe to branch on. --- ## Documentation | Document | Contents | |---|---| | [SECURITY.md](SECURITY.md) | Design, key space, threat model, attack analysis | | [docs/FORMAT.md](docs/FORMAT.md) | **Normative format specification**, with examples | | [docs/benchmark.md](docs/benchmark.md) | Measured throughput and the profiling behind it | | [docs/API.md](docs/API.md) | Complete Python API reference | | [docs/CLI.md](docs/CLI.md) | Command line reference and troubleshooting | | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Internal design and module map | | [docs/BUILDING.md](docs/BUILDING.md) | Building, testing and releasing | | [CHANGELOG.md](CHANGELOG.md) | Release history | --- ## Development ```bash pip install -e ".[dev]" pytest # run the test suite python -m build # build sdist + wheel twine check dist/* # validate package metadata ``` ### Repository layout ``` ChaosCrypt/ ├── README.md SECURITY.md LICENSE CHANGELOG.md ├── docs/ ├── pyproject.toml ├── dist/ └── chaoscrypt/ ├── __init__.py public API and the ChaosCrypt facade ├── _core.py the algorithm and the pipelines ├── _header.py the self-describing header ├── cli.py argument-driven command line interface ├── tui.py interactive bilingual interface ├── errors.py the unified error hierarchy ├── i18n.py UI strings ├── tests/ test suite, including frozen vectors ├── examples/ runnable examples └── legacy/ the original implementation, for reference ``` --- ## Licence [MIT](LICENSE) — provided as-is, without warranty of any kind. ChaosCrypt has not been independently audited. It is intended for obfuscation, personal use, and research or teaching. Do not deploy it where an audited, standardised cryptographic primitive is required.