Skip to main content

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 License Dependencies


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)

Source distribution for chaoscrypt 4.2.6
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)

Table of built distributions (wheels) for chaoscrypt 4.2.6
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

4.2.6 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page