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.
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 are the right tools for production
systems, regulated data, and long-lived secrets.
See SECURITY.md for the full design and threat analysis, and 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
<payload>
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.
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 |
from chaoscrypt import ChaosCrypt
cc = ChaosCrypt(mode="raw", encoding="base64", mid="bt")
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.
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.
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 for the legacy standard.
Installation
pip install chaoscrypt
Requires Python 3.8 or newer. No third-party runtime dependencies.
Three ways to use it
1. As a library
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:
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_<Detail>_<Code>:
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:
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 for the full reference.
3. As an interactive TUI
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 | Design, key space, threat model, attack analysis |
| docs/FORMAT.md | Normative format specification, with examples |
| docs/benchmark.md | Measured throughput and the profiling behind it |
| docs/API.md | Complete Python API reference |
| docs/CLI.md | Command line reference and troubleshooting |
| docs/ARCHITECTURE.md | Internal design and module map |
| docs/BUILDING.md | Building, testing and releasing |
| CHANGELOG.md | Release history |
Development
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 — 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.
Metadata
Release files for chaoscrypt 4.2.6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| chaoscrypt-4.2.6.tar.gz | 133.5 kB | Without provenance | Details for chaoscrypt-4.2.6.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| chaoscrypt-4.2.6-py3-none-any.whl | Python 3 | none | any | Details for chaoscrypt-4.2.6-py3-none-any.whl |
Total release size: 186.9 kB
Release files / chaoscrypt-4.2.6.tar.gz
| Download URL | chaoscrypt-4.2.6.tar.gz |
|---|---|
| Size | 133.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a97fbfa11f5cc3ab742cc9a65107e9d9615cdeb60d403ee847fba043b49bed26
|
|
BLAKE2b-256 checksum How to use checksums |
398f5e7dea8511b000be3f7b19b90f8f3c45ab488db19a5ee70ab78052125afb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.4
|
Release files / chaoscrypt-4.2.6-py3-none-any.whl
| Download URL | chaoscrypt-4.2.6-py3-none-any.whl |
|---|---|
| Size | 53.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9f18359656adc099415a9119c46242a1369f842f8f5e3bea3bc4498125b3efb5
|
|
BLAKE2b-256 checksum How to use checksums |
a8cfea9ee209a40ff578b37b52866590e5052ba1d007636e44be05e497de17e4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.4
|
Security for chaoscrypt 4.2.6
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.