Files
ChaosCrypt/SECURITY.md
T
dvs 2529edac1d v2.1.6: Restructure as a distributable library
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
2026-09-27 17:03:05 +08:00

20 KiB
Raw Permalink Blame History

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 plaintext
  • B = Base64(P) be its standard Base64 encoding (RFC 4648)
  • K_sys = (U, L, D, E, K_long, K_short, F) be the system key, where
    • U : {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 alphanumerics
    • E : {0,1,2,3} → Σ is a random injection (Base64 padding counts)
    • K_long ∈ {0–9a–f}^4096 is the long key
    • K_short ∈ {0–9a–f}^512 is the short key
    • F ∈ {0,1}^10 is the case-flip pattern
  • K_user be 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 of B through U, L or D depending on its class. Each = in B is removed and the padding count is encoded via E into a trailing marker.
  • Flip(s, F) swaps the case of the i-th character when F[i mod 10] = 1 and that character is a letter.
  • Reverse(s) reverses the whole string.
  • XorDynamic(s, K_long) XORs s against K_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 length n using three rotating expansion modes.
  • XorFinal(s, K) XORs s against DeriveKey(..., |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

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:

  1. n is the message length, so each distinct length yields a distinct keystream. Recovering one does not enable decryption of another.
  2. K_stream is the output of a non-invertible mixing pipeline; recovering it does not yield K_user or K_short.
  3. 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 via DeriveKey, 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.

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:

  1. alternating interleaving of the password and short key;
  2. left-shift, right-shift and XOR operations, cycled by position;
  3. grouped permutation across 4-byte blocks;
  4. whole-string reversal;
  5. extension to length n using 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 3 are 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.