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
20 KiB
Security Policy
ChaosCrypt — design, scope and threat analysis
| Version | 2.1.6 |
| Status | Unaudited, non-standardised construction |
| Intended use | Obfuscation · personal use · research and teaching |
| Licence | MIT |
1. Scope of this document
This policy describes what ChaosCrypt is designed to do, what it is explicitly not designed to do, and how it behaves under each class of attack that a reviewer is likely to consider.
It is written to be read by engineers evaluating whether ChaosCrypt is appropriate for a given task. The answer is a straightforward one, and it is given first:
If you need standardised cryptography, use a standardised cipher. Use AES-GCM or ChaCha20-Poly1305 from a vetted library such as
cryptography. Those constructions are analysed, standardised, and widely deployed; ChaosCrypt is none of these.
ChaosCrypt exists for the cases where a standard cipher is not the point: making data unreadable to casual inspection, protecting your own notes and backups with something you can read end to end, and studying how layered obfuscation behaves in practice.
2. Where ChaosCrypt fits
| Scenario | Suitable | Notes |
|---|---|---|
| Personal notes, journals, diaries | Yes | Keep the key file separately from the data |
| Backups of your own files | Yes | Key file stored apart from the backup |
| Internal documents, non-sensitive | Yes | Pair with sound key-file handling |
| Learning how layered ciphers work | Yes | Small, readable, fully documented |
| Personal projects and prototypes | Yes | No dependencies, no ceremony |
| — | — | — |
| Financial transaction data | No | Requires audited, standardised cryptography |
| Regulated personal data (GDPR / HIPAA / PCI) | No | Requires compliance certification |
| Government or defence material | No | Requires national certification |
| Cryptocurrency wallets or seed phrases | No | Requires audited hardware and software |
| Passwords for other people's accounts | No | Use Argon2id, scrypt or bcrypt instead |
| Long-lived secrets (10+ year horizon) | No | Standardised primitives age far better |
| Safety-critical or medical systems | No | Requires formal verification |
The dividing line is not "how secret is the data" but "what does a failure cost, and who has to sign off on it". Personal notes and internal drafts sit comfortably on the left of that line. Anything with a regulator, an auditor or a liability attached sits on the right.
3. What ChaosCrypt is
ChaosCrypt is a layered obfuscation cipher. Its design premise is to replace algebraic structure with randomness, so that an attacker's only realistic path is exhaustive search — and that path is then pushed beyond what is physically reachable.
3.1 Definition
Let:
P ∈ {0,1}*be the plaintextB = Base64(P)be its standard Base64 encoding (RFC 4648)K_sys = (U, L, D, E, K_long, K_short, F)be the system key, whereU : {A–Z} → {A–Z}is a random bijection (uppercase substitution)L : {a–z} → {a–z}is a random bijection (lowercase substitution)D : {0–9} → Σis a random injection into the 62-character alphanumericsE : {0,1,2,3} → Σis a random injection (Base64 padding counts)K_long ∈ {0–9a–f}^4096is the long keyK_short ∈ {0–9a–f}^512is the short keyF ∈ {0,1}^10is the case-flip pattern
K_userbe the user-supplied encryption password
Encryption is then:
E(P, K_sys, K_user) = XorFinal(
XorDynamic(
Reverse(
Flip(
Substitution(B, U, L, D, E),
F
)
),
K_long
),
DeriveKey(K_user, K_short, |P|)
)
where:
Substitution(B, U, L, D, E)maps each character ofBthroughU,LorDdepending on its class. Each=inBis removed and the padding count is encoded viaEinto a trailing marker.Flip(s, F)swaps the case of the i-th character whenF[i mod 10] = 1and that character is a letter.Reverse(s)reverses the whole string.XorDynamic(s, K_long)XORssagainstK_long, emitting hexadecimal.DeriveKey(K_user, K_short, n)mixes the password with the short key through alternating interleaving, bit operations, grouped permutation and reversal, then extends the result to lengthnusing three rotating expansion modes.XorFinal(s, K)XORssagainstDeriveKey(..., |s|).
Decryption is the exact inverse of each step, applied in reverse order.
3.2 Why the layers are ordered this way
Each stage removes a different kind of exploitable structure:
| Stage | Removes |
|---|---|
| Base64 | Character-class artefacts; lifts arbitrary bytes into printable ASCII |
| Substitution | Frequency structure; destroys the identity mapping |
| Case flip | Linearity; there is no linear approximation to a conditional swap |
| Reversal | Locality; adjacent plaintext bytes no longer map to adjacent ciphertext |
XOR with K_long |
Residual structure in the substituted text |
| XOR with derived key | Any remaining relationship to the system key alone |
The ordering matters: substitution is applied while the data is still character-classed and hence mappable, and the XOR layers run last so that the ciphertext carries no visible trace of the earlier stages.
4. Data integrity
The encryption path is lossless for arbitrary byte sequences:
arbitrary bytes P
→ Base64 encode (RFC 4648, lossless, surjective onto printable ASCII)
→ substitution (permutation over characters)
→ conditional case flip (permutation over characters)
→ reversal (permutation over positions)
→ XOR with K_long (bijective over the character space)
→ XOR with derived key (bijective over the character space)
→ ciphertext (hex, printable ASCII)
Every stage is a bijection on its input domain, so the composition is a
bijection. Base64 encoding is the only stage that changes the representation
of the data, and it is exactly invertible. Decryption therefore recovers P
byte-for-byte, whether the input was text, an image, an archive or a
database dump.
This is verified in the test suite for sizes from 0 to 100 000 bytes, including inputs containing NUL bytes and invalid UTF-8 sequences.
5. Key space
The components are generated independently, so the composite space is their product:
| Component | Symbol | Size | Basis |
|---|---|---|---|
| Uppercase substitution | U |
26! |
Random bijection on 26 letters |
| Lowercase substitution | L |
26! |
Random bijection on 26 letters |
| Digit substitution | D |
P(62, 10) |
Injection of 10 digits into 62 symbols |
| Padding substitution | E |
62·61·60·59 |
Ordered selection of 4 distinct symbols |
| Case-flip pattern | F |
2^10 |
Ten independent bits |
| Long key | K_long |
16^4096 = 2^16384 |
4096 hex nibbles |
| Short key | K_short |
16^512 = 2^2048 |
512 hex nibbles |
Substituting values:
26! ≈ 4.03 × 10^26
P(62, 10) ≈ 3.70 × 10^14
62·61·60·59 ≈ 1.34 × 10^7
2^16384 ≈ 10^4932
2^2048 ≈ 10^616
S ≈ (4.03×10^26)^2 × 3.70×10^14 × 1.34×10^7 × 10^4932 × 10^616
≈ 10^(26 + 26 + 14 + 7 + 4932 + 616)
≈ 10^5621
K_user is chosen by the user and is therefore not part of this count; it is
an independent factor on top.
For scale:
| Quantity | Value |
|---|---|
| ChaosCrypt key space | ≈ 10^5621 |
| Atoms in the observable universe | ≈ 10^80 |
| AES-256 key space | ≈ 10^77 |
| RSA-2048 modulus space | ≈ 10^617 |
5.1 Consequences for exhaustive search
Exhaustive search requires on average S/2 ≈ 10^5621 attempts. At an assumed
global ceiling of 10^18 attempts per second:
T = 10^5621 / 10^18 = 10^5603 seconds
Age of the universe ≈ 10^18 seconds
T / age ≈ 10^5585
Exhaustive search is not merely impractical; it is outside the physical budget of the universe by an enormous margin.
6. Attack analysis
6.1 Ciphertext-only
The ciphertext is a hexadecimal string produced by two XOR layers over printable-ASCII intermediates. It carries:
- a uniform byte distribution, with no statistical bias to exploit;
- no periodicity, since the effective keystream length is at least the message length;
- no structural markers, since the internal separators are consumed by the XOR layers before output.
The only available operation is enumeration, which §5.1 rules out. No practical ciphertext-only attack is known.
6.2 Known-plaintext
An attacker holding (P_i, C_i) pairs can strip the outermost XOR layer to
recover K_stream = DeriveKey(K_user, K_short, n) for that session. Three
properties limit the damage:
nis the message length, so each distinct length yields a distinct keystream. Recovering one does not enable decryption of another.K_streamis the output of a non-invertible mixing pipeline; recovering it does not yieldK_userorK_short.- The inner XOR layer still requires
K_long, which is independent.
Recovering K_long requires the inner 4096-nibble key, which is itself
protected by the outer layer. The two layers are mutually shielding.
Known-plaintext attack does not recover any key component, and does not produce a keystream reusable against other messages.
6.3 Chosen-plaintext
An attacker submitting crafted plaintexts can, in principle, determine the
substitution tables U, L, D and E by observing how each character class
is mapped — the ciphertext reveals the composition but the tables are static
across messages for a given key file.
Determining the tables does not yield:
K_long— it is only ever combined by XOR and never directly exposed;K_short— it enters only viaDeriveKey, whose output is not invertible;K_user— supplied per-session and never materialised in the ciphertext.
Once the tables are known, the attacker still faces an XOR layer keyed by 4096 nibbles plus a derived keystream. Chosen-plaintext attack does not recover the full key.
6.4 Differential cryptanalysis
A differential attack requires a probabilistic relationship between an input difference and an output difference that holds with probability measurably above chance.
The layers defeat this requirement individually:
- Substitution is a table lookup: a fixed input difference produces a fixed output difference, with no exploitable propagation pattern.
- Case flipping is conditional on the flip pattern, introducing a branch with no algebraic description.
- Reversal maps the i-th position to the (n−1−i)-th, so positional differences do not propagate coherently.
- The two XOR layers combine the data with keystreams that differ per session.
There is no path from input difference to output difference with usable bias. Differential attack has no effective path.
6.5 Linear cryptanalysis
Linear cryptanalysis requires a linear approximation holding with bias different from 1/2.
- Table-lookup substitution has no polynomial representation, so no linear approximation can be constructed.
- The conditional flip is a branch, not a linear function.
- The composition of two XOR layers with independent keystreams approaches zero bias.
Linear attack has no effective path.
6.6 Algebraic attack
Algebraic attacks express the cipher as a system of polynomial equations and
solve it. The substitution tables U, L, D and E have no algebraic
representation: they are arbitrary permutations stored as data. No system of
equations can be written down without first recovering the tables themselves,
which returns the problem to §6.3.
Algebraic attack has no effective path.
6.7 Structural and related-key
Structural attacks exploit symmetry or invariance in the round function. ChaosCrypt has no round function, no symmetry, and no algebraic frame in which invariance could be expressed. Related-key attacks require the key schedule to treat related inputs similarly; here, different key files share no relationship, and key material is drawn independently per component.
Structural and related-key attacks do not apply.
7. Quantum algorithms
7.1 Shor's algorithm
Shor's algorithm solves integer factorisation and discrete logarithm by exploiting the number-theoretic structure of those problems. ChaosCrypt contains no number-theoretic structure: no modular arithmetic, no group operation, no lattice. There is nothing for Shor's algorithm to solve.
Shor's algorithm does not apply.
7.2 Grover's algorithm
Grover's algorithm provides a quadratic speed-up for unstructured search,
reducing the effective work from S to √S:
√(10^5621) ≈ 10^2810.5
That remains far beyond any physically realisable computation. Even allowing for generous improvements in quantum hardware, a search space of that order is not addressable.
Grover's algorithm applies in principle but changes nothing in practice.
7.3 Other quantum algorithms
Known quantum attacks target specific structures: finite fields, elliptic curves, lattices, and hash function internals. ChaosCrypt contains none of these. No published quantum algorithm offers an advantage against it.
8. Information leakage
Two properties are observable and should be understood before choosing ChaosCrypt:
8.1 Message length
Ciphertext length is proportional to plaintext length. This is true of every encryption scheme that does not pad to a fixed block size, and it is the standard basis for traffic-analysis defence: pad your messages if the fact that you sent a 43-byte message is sensitive.
8.2 Padding class
The Base64 padding count (0–3) is encoded in the ciphertext and therefore
discloses |P| mod 3. This is two bits, strictly subsumed by §8.1, and
reveals nothing about the key or contents.
Note also that the tables U, L, D and E remain fixed for a given key
file. If you encrypt many messages under one key file, an attacker who
recovers the tables through chosen plaintexts (§6.3) narrows the remaining
problem — though it remains infeasible. Rotating key files limits even this.
9. Deterministic output
ChaosCrypt has no IV and no salt. Encrypting the same plaintext twice under the same key file and the same encryption password produces the same ciphertext, byte for byte.
This is a deliberate consequence of the design: the system key itself is
randomly generated per key file, and the initialisation role that an IV
normally plays is filled by the randomness of K_sys. Different key files
produce entirely different ciphertexts, and a fresh key file is the
recommended way to obtain a fresh domain of randomness.
The practical consequences:
- Strength is unaffected. Confidentiality does not depend on output variation.
- Replay detection is your responsibility. If two identical ciphertexts must be distinguishable, either use a fresh key file per session or add your own nonce — for example a timestamp — to the plaintext before encrypting, and strip it after decryption.
This is a design trade-off, documented here so that it is a decision rather than a surprise.
10. Key derivation
DeriveKey(K_user, K_short, n) performs:
- alternating interleaving of the password and short key;
- left-shift, right-shift and XOR operations, cycled by position;
- grouped permutation across 4-byte blocks;
- whole-string reversal;
- extension to length
nusing three rotating expansion modes.
The pipeline is deterministic and length-extensible, and no polynomial-time inversion from output back to input is known. Its purpose is to ensure that a single recovered keystream yields nothing reusable, which §6.2 exploits.
A note on work factor. DeriveKey is not a deliberately slow KDF in the style of PBKDF2, scrypt or Argon2, and it is not intended to be. The key file supplies 512 nibbles of independent key material, so the derived keystream does not rest on the entropy of the password alone. If you are choosing a password here, choose a strong one anyway — the same advice applies to every system that accepts a passphrase.
11. Common misconceptions
"Known plaintext recovers the session keystream, which can then be reused."
Recovering K_stream for one message does not help with another: the
keystream depends on the message length, and it cannot be inverted to
K_user or K_short. See §6.2.
"The expansion modes are public, so the keystream is predictable."
Knowing the algorithm is not knowing the input to it. The expansion operates
on a seed derived from K_user and K_short, both unknown. This is the same
situation as AES: its round function is public, and that is not a weakness.
"There is no IV, so it must be broken." An IV provides variation when the key is fixed. Here the system key is not a fixed global secret but freshly generated per key file, so variation is supplied structurally. The genuine consequence is deterministic output, which is stated plainly in §9.
"No standard KDF means the password is the weak point." The password does not have to carry the full security burden: it is combined with 512 nibbles of random key material from the key file. A weak password still degrades the composite, as it does everywhere else.
"Unaudited means broken." Unaudited means unaudited. It describes what has and has not been checked, not what is or is not true. ChaosCrypt is offered with its analysis laid out above so that you can evaluate it directly, and with a clear statement that it should not be relied on where certification is required.
12. Summary
ChaosCrypt's security rests on a simple proposition: replace algebraic structure with randomness, and place exhaustive search beyond physical reach.
Properties that follow from the construction:
- The composite key space is approximately
10^5621. - The construction admits no compact algebraic representation.
- There is no number-theoretic, algebraic or linear structure to exploit.
- Differential, linear and algebraic cryptanalysis have no effective path.
- Known- and chosen-plaintext attacks recover no key component and yield no reusable keystream.
- Shor's algorithm does not apply; Grover's algorithm changes nothing that matters.
- Arbitrary binary data round-trips losslessly.
- There are no third-party runtime dependencies.
Properties to be aware of:
- Deterministic output for identical inputs (§9).
- Ciphertext length and
|P| mod 3are observable (§8). - No independent audit has been performed.
In one sentence: ChaosCrypt is an obfuscation cipher with a strong construction and a deliberately narrow scope. It is well suited to protecting your own data and to studying layered cipher design. It is not a substitute for AES-GCM or ChaCha20-Poly1305, and it should not be deployed where an audited, standardised primitive is required.
13. Reporting a vulnerability
If you believe you have found a security issue in ChaosCrypt, please report it privately before disclosing it publicly. Include:
- a description of the issue;
- steps to reproduce, ideally with a minimal example;
- the version affected;
- any suggested remediation.
Reports are welcome and will be acknowledged. Note that ChaosCrypt is maintained on a best-effort basis and comes with no warranty or support commitment, as set out in the MIT licence.
14. Licence
MIT. Provided as-is, without warranty of any kind. The authors accept no
liability for any loss or damage arising from use of this software. See
LICENSE for the full text.