Every key file and ciphertext now carries a header that states how it was produced: magic, two fixed markers, and a complete JSON configuration record. A reader takes its parameters from the artefact rather than from the caller. This is an incompatible format change. Headerless input is rejected with E017; pre-4.2.6 material is read through a compatibility API that wraps it in a minimal header and then uses the ordinary path, so the strict path stays strict. Added - Self-describing header on all artefacts, with a normative specification in docs/FORMAT.md - E017 MissingMagicHeader and E018 MalformedHeader - Byte pipeline for turbo and raw: the XOR layers exchange raw bytes rather than hexadecimal text, cutting expansion from 5.33x to 2.00x and raising throughput about 4x. The old behaviour is available as mid="hex". - Selectable output encoding for turbo and raw: hex (2.00x) or base64 (1.33x) - Legacy compatibility API: wrap_legacy, decrypt_legacy, decrypt_legacy_auto, load_legacy_keys - Frozen reference vectors covering every mode, encoding and intermediate - docs/benchmark.md with measured throughput and the profiling behind it Changed - Default mode is fast: byte-for-byte compatible with the original algorithm, roughly 30x quicker - Substitution, case flipping and the printable fold use bytes.translate over precomputed tables - XOR layers use one big-integer operation instead of a per-byte loop - Keystream derivation caches length-independent base material; expansion uses cached translation tables and list accumulation rather than str += - _get_dynamic_key repeats by multiplication. The loop version was quadratic: covering a 5.6 MB intermediate took 866 ms, now 3 ms, output unchanged. - _derive_final_key decodes only the prefix the output consumes - The decrypt path no longer copies or scans the whole artefact: a redundant strip(), a full-string int(payload, 16), and three whole-string slices in strip_header were removed. Decryption at 512 KiB went from 34 to 87 MB/s. - Documentation rewritten for 4.2.6; all eleven markdown files are English Fixed 1. Key derivation is no longer quadratic (_get_dynamic_key and _expand_keystream_slow shared the str += pattern) 2. Two hex-intermediate pipelines were asymmetric, so a turbo or raw artefact written with mid="hex" could not be read back 3. change_key_password and export_key_text wrote artefacts without a header 4. The constructor accepted encoding="base64" while the header records out="base"; both spellings are now accepted 5. A payload that is not valid hexadecimal reports E010 (MalformedCiphertext) rather than E011 (DecryptionFailed) 6. The TUI encoding menu referenced a missing translation Security - Format break from pre-4.2.6 artefacts, documented rather than accidental - fast is not a weaker mode: the frozen vectors assert identical output - The header adds no secrecy and is not authenticated; an application that must detect header tampering should MAC the whole artefact Performance - raw with the default bt intermediate: ~60 MB/s encryption, ~70 MB/s decryption, ciphertext 2.00x the payload - Throughput holds steady from 64 KiB to 1 GiB - The original implementation managed 0.08 MB/s
10 KiB
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.