Restructure ChaosCrypt from a single-file script into a complete, installable Python package with three interfaces: a typed Python API, an argument-driven CLI, and a bilingual interactive TUI. The algorithm itself is unchanged. Ciphertexts and key files remain fully interoperable with the original implementation in both directions, which is enforced by dedicated tests rather than merely documented. Added - Library API: ChaosCrypt facade plus ChaosCryptCore for the raw algorithm - Unified error hierarchy: 16 named types, all ChaosCryptError subclasses, rendering as ChaosCrypt_ERR_<Detail>_<Code> - CLI: keygen, encrypt, decrypt, file, info, chpwd, tui, with --json output, stdin/stdout piping, and three password sources per secret - Bilingual TUI: English default, runtime switch to Chinese, getpass password entry with a non-TTY fallback that keeps it scriptable - Binary and file support: encrypt_bytes/decrypt_bytes and encrypt_file/decrypt_file - Key management: change_key_password rewraps without altering key material; export_key_text/load_from_text move a key without touching disk - Documentation: SECURITY.md with the full design and threat analysis, plus docs/ covering the API, CLI, architecture and build process - Test suite: 92 tests across round-trips, binary safety, key management, error types, CLI, TUI, i18n and legacy interoperability - Packaging: pyproject.toml, setup.py compatibility shim, MANIFEST.in, py.typed, examples, MIT licence Fixed - Conflicting --pwd option between the -p and -P groups prevented the CLI from starting at all - Wrong key file password reported as file corruption (E002); structural validation now distinguishes it from a damaged file (E003) - export_key_text produced key material without loading it into the instance - Non-hexadecimal input was accepted as ciphertext and silently decrypted into garbage, making corruption indistinguishable from success; malformed input now raises E010 before any processing - TUI failed under piped input because getpass requires a TTY - TUI kept reading the default key file name after generating a new one Changed - Source tree reorganised: the package lives at chaoscrypt/, with tests, examples and legacy alongside it; documentation and build artefacts at the repository root - Code comments unified in English; public docstrings document parameters, return values and raised exceptions - English is now the default UI language - ChaosCryptChat removed from the repository - Attribution updated to Dvs (DvsXT); project URLs point to Gitea
434 lines
14 KiB
Markdown
434 lines
14 KiB
Markdown
# ChaosCrypt
|
|
|
|
**A chaos-based obfuscation cipher with a bilingual TUI, a full CLI, and a clean Python API.**
|
|
|
|
[](https://www.python.org/)
|
|
[](LICENSE)
|
|
[](#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. ChaosCrypt is not a
|
|
replacement for them and does not claim to be.
|
|
|
|
See [SECURITY.md](SECURITY.md) for the complete design description, key-space
|
|
derivation, and attack analysis.
|
|
|
|
---
|
|
|
|
## Why it is worth a look
|
|
|
|
The absence of an audit says nothing about the strength of the construction.
|
|
ChaosCrypt is deliberately built to remove every kind of structure that
|
|
classical cryptanalysis relies on, and the result is a design with real
|
|
substance behind it:
|
|
|
|
**A key space of roughly 10^5621.** The system key is the product of two
|
|
independent 26-letter bijections, a 10-into-62 injection, an ordered selection
|
|
of 4 padding symbols, a 10-bit flip pattern, a 4096-nibble long key and a
|
|
512-nibble short key. For comparison: AES-256 offers about 10^77, and the
|
|
observable universe contains about 10^80 atoms.
|
|
|
|
**Five layers, each removing a different class of structure.**
|
|
|
|
```
|
|
plaintext
|
|
| Base64 lift arbitrary bytes into printable ASCII
|
|
| substitution destroy frequency structure
|
|
| conditional case flip remove linearity
|
|
| whole-message reversal destroy locality
|
|
| XOR with long key erase residual substituted structure
|
|
| XOR with derived key sever any link to the key file alone
|
|
ciphertext
|
|
```
|
|
|
|
**No algebraic structure to attack.** The substitution tables are arbitrary
|
|
permutations stored as data, so there is no polynomial representation.
|
|
Differential, linear and algebraic cryptanalysis all require a compact
|
|
algebraic description that simply does not exist here.
|
|
|
|
**No number-theoretic structure either.** There is no modular arithmetic, no
|
|
group operation and no lattice, so Shor's algorithm has nothing to solve.
|
|
Grover's algorithm reduces the search to about 10^2810 — still far beyond any
|
|
physically realisable computation.
|
|
|
|
**The two XOR layers shield each other.** An attacker who recovers the outer
|
|
keystream still faces the 4096-nibble long key, and no keystream recovered
|
|
from one message is reusable against another, because the derivation is
|
|
parameterised by message length.
|
|
|
|
**Lossless for arbitrary binary data.** Every stage is a bijection, so images,
|
|
archives and database dumps round-trip byte-for-byte. Verified in the test
|
|
suite from 0 to 100,000 bytes, including NUL bytes and invalid UTF-8.
|
|
|
|
**Zero third-party runtime dependencies.** Pure standard library. Nothing to
|
|
audit in your dependency tree, nothing to break on upgrade, and `pip install`
|
|
is immediately usable.
|
|
|
|
**A real interface.** A bilingual interactive TUI for interactive use, a
|
|
complete argument-driven CLI for automation, and a typed Python API for
|
|
embedding — all three backed by the same sixteen-code error hierarchy.
|
|
|
|
---
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
pip install chaoscrypt
|
|
```
|
|
|
|
From source:
|
|
|
|
```bash
|
|
git clone https://git.dvscloud.net/dvs/ChaosCrypt
|
|
cd ChaosCrypt
|
|
pip install .
|
|
```
|
|
|
|
**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()
|
|
|
|
# Generate a key file once, then keep it somewhere safe.
|
|
cc.create_key("key-file-password", "my.key")
|
|
|
|
# Encrypt and decrypt.
|
|
token = cc.encrypt("hello world", "encryption-password")
|
|
assert cc.decrypt(token, "encryption-password") == "hello world"
|
|
```
|
|
|
|
One-shot helpers, when you do not want to manage an instance:
|
|
|
|
```python
|
|
import chaoscrypt
|
|
|
|
chaoscrypt.create_key("key-file-pwd", "my.key")
|
|
ct = chaoscrypt.encrypt("secret", "user-pwd", "my.key", "key-file-pwd")
|
|
pt = chaoscrypt.decrypt(ct, "user-pwd", "my.key", "key-file-pwd")
|
|
```
|
|
|
|
Binary data and files:
|
|
|
|
```python
|
|
from chaoscrypt import ChaosCrypt
|
|
|
|
cc = ChaosCrypt("my.key", "key-file-pwd", auto_load=True)
|
|
|
|
raw = open("photo.png", "rb").read()
|
|
ct = cc.encrypt_bytes(raw, "encryption-password")
|
|
open("photo.cc", "w").write(ct)
|
|
|
|
restored = cc.decrypt_bytes(ct, "encryption-password")
|
|
open("photo.restored.png", "wb").write(restored)
|
|
|
|
# Or use the file helpers directly.
|
|
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 subclass of `ChaosCryptError` and
|
|
renders as `ChaosCrypt_ERR_<Detail>_<Code>`:
|
|
|
|
```python
|
|
from chaoscrypt import ChaosCrypt, ChaosCryptError
|
|
|
|
cc = ChaosCrypt()
|
|
try:
|
|
cc.load("my.key", "wrong-password")
|
|
except ChaosCryptError as e:
|
|
print(e) # ChaosCrypt_ERR_KeyPasswordIncorrect_E003
|
|
print(e.code) # E003
|
|
print(e.detail) # KeyPasswordIncorrect
|
|
```
|
|
|
|
Catching `ChaosCryptError` handles everything the library can raise.
|
|
|
|
### 2. As a command line tool
|
|
|
|
**No arguments** launches the interactive TUI:
|
|
|
|
```bash
|
|
chaoscrypt
|
|
```
|
|
|
|
**With arguments** it is a scriptable CLI:
|
|
|
|
```bash
|
|
# Generate a key file.
|
|
chaoscrypt keygen -k my.key --key-pwd-env KEY_PWD
|
|
|
|
# Encrypt and decrypt text.
|
|
chaoscrypt encrypt "hello world" -p mypass -k my.key -P keypass
|
|
chaoscrypt decrypt "1a2b3c..." -p mypass -k my.key -P keypass
|
|
|
|
# Files (binary-safe).
|
|
chaoscrypt file encrypt photo.png -p mypass -k my.key -P keypass
|
|
chaoscrypt file decrypt photo.png.cc -p mypass -k my.key -P keypass
|
|
|
|
# Key file metadata.
|
|
chaoscrypt info -k my.key -P keypass --json
|
|
|
|
# Rotate the key file password.
|
|
chaoscrypt chpwd -k my.key -P oldpass --new-pwd newpass
|
|
```
|
|
|
|
Working with pipes and files:
|
|
|
|
```bash
|
|
# JSON output for programmatic use.
|
|
chaoscrypt --json encrypt "data" -p pw -k my.key -P kp
|
|
|
|
# Read from stdin, write to stdout.
|
|
echo "hello" | chaoscrypt encrypt - -p pw -k my.key -P kp
|
|
chaoscrypt decrypt - -p pw -k my.key -P kp < secret.cc
|
|
|
|
# Read and write files directly.
|
|
chaoscrypt encrypt -i in.txt -o out.cc -p pw -k my.key -P kp
|
|
```
|
|
|
|
**Supplying passwords.** Three options, in ascending order of safety:
|
|
|
|
| Method | Example | Notes |
|
|
|---|---|---|
|
|
| Inline | `-p mypass` | Visible in shell history — not recommended |
|
|
| Environment variable | `--pwd-env MY_PWD` | Suitable for CI/CD |
|
|
| Password file | `--pwd-file ~/.cc.pwd` | Reads the last non-empty line — recommended |
|
|
|
|
Note the distinction: `-p`/`--pwd` is the **encryption password** that protects
|
|
your data, while `-P`/`--key-pwd` is the **key file password** that unlocks the
|
|
key file.
|
|
|
|
**Exit codes:** `0` success, `1` runtime error, `2` usage error.
|
|
|
|
### 3. As an interactive TUI
|
|
|
|
Run `chaoscrypt` with no arguments (or `python -m chaoscrypt`):
|
|
|
|
```
|
|
+================================================================+
|
|
| ChaosCrypt - Chaos Obfuscation Cipher v2.1.6 |
|
|
+================================================================+
|
|
ChaosCrypt is an unaudited, non-standardised cipher. It is intended for
|
|
obfuscation, personal use and study -- not for production systems.
|
|
|
|
[ ] No key loaded yet. [encryption.key]
|
|
|
|
------------------------------------------------------------------
|
|
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
|
|
[a] About / security notice
|
|
[q] Quit
|
|
------------------------------------------------------------------
|
|
```
|
|
|
|
- **Bilingual**: option `[9]` switches between English and Chinese at runtime,
|
|
and every label follows.
|
|
- **Passwords are not echoed**: input uses `getpass` on a terminal.
|
|
- **Helpful when a key is missing**: offers to create one on the spot.
|
|
- **Errors are self-explanatory**: shown as `ChaosCrypt_ERR_..._Exxx` with a
|
|
short hint about the likely cause.
|
|
- **Degrades cleanly**: redirected or piped output drops colour and switches
|
|
to plain input, so the UI remains scriptable.
|
|
|
|
---
|
|
|
|
## The two-password model
|
|
|
|
ChaosCrypt separates the secret that protects the key file from the secret
|
|
used for each message. Keeping them distinct is what makes key rotation cheap:
|
|
|
|
| Password | Purpose | Where it lives |
|
|
|---|---|---|
|
|
| **Key file password** | Wraps and unwraps `encryption.key` | Only in your head |
|
|
| **Encryption password** | Used per encryption/decryption operation | Only in your head |
|
|
|
|
The system key material — substitution tables, long key, short key, flip
|
|
pattern — is stored in the key file, protected by the key file password. The
|
|
encryption password is mixed with the short key at runtime to derive the
|
|
session keystream.
|
|
|
|
> **To decrypt your data you need all three:** the key file, the key file
|
|
> password, and the encryption password. Back them up separately. Losing any
|
|
> one makes recovery impossible — there is no backdoor.
|
|
|
|
---
|
|
|
|
## How it works
|
|
|
|
```
|
|
plaintext P
|
|
|
|
|
+-- Base64 encode -----------------> printable ASCII
|
|
|
|
|
+-- Letter substitution -----------> two independent 26! bijections
|
|
|
|
|
+-- Conditional case flip ---------> 10-bit pattern, adds non-linearity
|
|
|
|
|
+-- Whole-message reversal --------> destroys local correlation
|
|
|
|
|
+-- XOR with long key -------------> 4096-nibble keystream
|
|
|
|
|
+-- XOR with derived keystream ----> 512-nibble short key + password
|
|
|
|
|
ciphertext C (hexadecimal)
|
|
```
|
|
|
|
Decryption applies the exact inverse of each step in reverse order.
|
|
|
|
The packaged library is **bit-for-bit equivalent** to the original
|
|
single-file implementation. Old key files, old ciphertexts, and the old
|
|
script remain mutually compatible in both directions — this is enforced by
|
|
the test suite, not merely asserted.
|
|
|
|
---
|
|
|
|
## FAQ
|
|
|
|
<details>
|
|
<summary><b>Why not just use AES?</b></summary>
|
|
|
|
If your goal is security, use AES-GCM or ChaCha20-Poly1305. They are audited,
|
|
standardised, and available in mature libraries. ChaosCrypt exists to explore
|
|
a different design premise — replacing algebraic structure with randomness —
|
|
and to serve obfuscation, personal use and teaching.
|
|
|
|
Judging a personal project against the standard applied to AES-256-GCM is a
|
|
category error, in the same way that judging a bicycle against Formula 1
|
|
regulations tells you nothing useful about the bicycle.
|
|
</details>
|
|
|
|
<details>
|
|
<summary><b>There is no IV. Is that a problem?</b></summary>
|
|
|
|
An IV creates output variation when the key is fixed. Here the system key is
|
|
freshly generated per key file and combined with your password, so variation
|
|
is supplied structurally rather than per message.
|
|
|
|
The real consequence is **deterministic output**: the same plaintext, key file
|
|
and encryption password produce the same ciphertext. Confidentiality is
|
|
unaffected. If you need two identical messages to be distinguishable — for
|
|
replay detection, say — use a fresh key file, or prepend your own nonce and
|
|
strip it after decryption. This is a documented design trade-off, not an
|
|
oversight. See [SECURITY.md §9](SECURITY.md).
|
|
</details>
|
|
|
|
<details>
|
|
<summary><b>What happens if I lose the key file or a password?</b></summary>
|
|
|
|
**Your data is unrecoverable.** This is by design: there is no backdoor, no
|
|
escrow, and no recovery path. Back up the key file, and keep both passwords in
|
|
a password manager.
|
|
</details>
|
|
|
|
<details>
|
|
<summary><b>Can I use this to protect cryptocurrency keys?</b></summary>
|
|
|
|
**No.** Use audited tooling designed for that purpose — a hardware wallet, or
|
|
`age` / `gpg` with a hardened configuration. ChaosCrypt is explicitly not
|
|
suitable for this.
|
|
</details>
|
|
|
|
<details>
|
|
<summary><b>Is it compatible with the original single-file script?</b></summary>
|
|
|
|
Yes, completely. The algorithm is implemented bit-for-bit identically. Old
|
|
key files load directly, old ciphertexts decrypt directly, and anything the
|
|
library produces is readable by the original script. The original
|
|
implementation is preserved under `chaoscrypt/legacy/` for exactly this
|
|
purpose, and interoperability is covered by dedicated tests.
|
|
</details>
|
|
|
|
<details>
|
|
<summary><b>How do I handle a password for a service that stores credentials?</b></summary>
|
|
|
|
Do not store user passwords with ChaosCrypt. Password storage has its own
|
|
requirements — a deliberately slow, memory-hard KDF with a per-user salt —
|
|
and the right choices are Argon2id, scrypt or bcrypt. ChaosCrypt is not a
|
|
password hashing function.
|
|
</details>
|
|
|
|
---
|
|
|
|
## 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/ additional documentation
|
|
├── pyproject.toml
|
|
├── dist/ build artefacts
|
|
└── chaoscrypt/ source tree
|
|
├── __init__.py public API and the ChaosCrypt facade
|
|
├── _core.py the algorithm
|
|
├── 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
|
|
├── examples/ runnable examples
|
|
└── legacy/ the original single-file implementation
|
|
```
|
|
|
|
---
|
|
|
|
## Documentation
|
|
|
|
| Document | Contents |
|
|
|---|---|
|
|
| [SECURITY.md](SECURITY.md) | Design, key space, threat model, attack analysis |
|
|
| [CHANGELOG.md](CHANGELOG.md) | Release history |
|
|
| [docs/API.md](docs/API.md) | Complete API reference |
|
|
| [docs/CLI.md](docs/CLI.md) | Command line reference |
|
|
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Internal design and module map |
|
|
|
|
---
|
|
|
|
## 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.
|