Files
ChaosCrypt/SECURITY.md
T
dvs dd49043171 v4.2.6: Self-describing format, byte pipeline, and a performance pass
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
2026-09-27 22:06:34 +08:00

34 KiB
Raw Permalink Blame History

Security Policy

ChaosCrypt — design, performance modes, threat analysis

Version 4.2.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 a reviewer is likely to consider. It covers the cipher, the four performance modes introduced in 4.2.6, and the trade-offs between them.

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 comes 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 in the reference mode is:

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. Performance modes

4.2.6 introduces four modes. Three of them change only the implementation; one changes the algorithm.

Mode Implementation Algorithm Ciphertext
reference original, per-character loops original original hex
fast C-level bulk operations identical identical to reference, byte for byte
turbo C-level bulk operations SHAKE256 keystream own hex format
raw C-level bulk operations byte pipeline + SHAKE256 own base64 format

4.1 The two extra settings

turbo and raw take two further settings, both recorded in the header:

Setting Values Effect
out hex, base Final output encoding. hex is 2.00x the payload, base 1.33x.
mid bt, hex Whether the XOR layers exchange raw bytes or hexadecimal text.

mid is the setting that matters for security: it determines how many structural layers stand between the ciphertext and the substituted text.

mid Layers between ciphertext and substitution Expansion
bt (default) two XOR layers 2.00x (hex out) or 1.33x (base out)
hex two XOR layers, each followed by a hex re-encoding 8.00x (hex out)

hex is offered for interoperability with the character pipeline's shape. It is not stronger: re-encoding between layers adds no key material, and it costs roughly 4x in time and size. bt is both faster and, if anything, marginally more resistant because the intermediate values are never constrained to a printable alphabet.

reference and fast are character pipelines; they always report mid="hex" and out="hex" and ignore both settings.

4.2 What each mode costs

Mode What changed Security impact
reference nothing none
fast loops → bytes.translate, big-integer XOR, table-cached expansion none
turbo keystream derivation replaced with SHAKE256; byte pipeline arguably improved
raw as turbo, but the long-key XOR layer is retained slightly weaker than turbo — the two XOR layers derive from one construction rather than two independent ones

fast is not a weaker mode. It performs the same arithmetic on the same values and produces the same bytes. Only the Python-level mechanics differ. The test suite enforces this: test_modes.py asserts that fast and reference produce identical ciphertext for every frozen reference vector, so the equivalence cannot silently stop holding.

turbo is not obviously weaker either. It replaces a bespoke expansion function with SHAKE256, a standardised extensible-output function. The seed binds the password, the short key, the long key and the requested length, and the long-key XOR layer is retained. The composite key space is unchanged in kind; the keystream generator is now one that has been publicly analysed.

raw is weaker, and deliberately so. It is the only mode that changes the structure of the cipher rather than its implementation. §9 analyses what is given up.

4.3 Cross-mode compatibility

Ciphertexts are not interchangeable between mode families:

reference fast turbo raw
reference ✓ ✓ ✗ ✗
fast ✓ ✓ ✗ ✗
turbo ✗ ✗ ✓ ✗
raw ✗ ✗ ✗ ✓

turbo and raw artefacts are also specific to their out and mid. The header states both, so a reader configured differently still reads the artefact correctly; the ordinary path takes its parameters from the header, not from the caller.

Attempting to decrypt across families either raises or produces unusable output; there is no silent misinterpretation. The CLI's --mode flag and the library's mode argument must match what was used to encrypt.


5. 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

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.

raw follows the same argument with the Base64 stage moved to the end and the XOR layers operating on bytes. It is equally lossless.

This is verified in the test suite for sizes from 1 to 100 000 bytes across all four modes, including inputs containing NUL bytes and invalid UTF-8 sequences.


6. 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.2 Key space per mode

The count above applies to reference, fast and turbo, which all retain both XOR layers and all seven key components.

raw retains the substitution tables, the flip pattern, the short key and the long key. Its keystream seed binds K_short, K_long, K_user and the layer index, so the composite space is still the product of the substitution tables and both key components — but the two XOR layers now derive from a single SHAKE256 call rather than two independently-seeded layers. The reduction is in the structure available to an attacker, not primarily in the raw count. See §9.


7. The self-describing header

Every artefact begins with a header: a magic value, two fixed markers, and a JSON record naming the mode, the intermediate representation, the output encoding, the algorithm and the key shape. The full specification is in docs/FORMAT.md.

7.1 What the header is for

It removes a silent-corruption hazard. Decrypting with the wrong mode or the wrong encoding yields garbage that is indistinguishable from a wrong password, and a caller who has to remember the parameters will eventually get it wrong. Recording them next to the payload means the artefact carries its own instructions.

7.2 What the header does not do

  • It adds no secrecy. The configuration is plaintext. It names parameters, not keys, and ksum is a truncated digest over public key shape.
  • It is not authenticated. An attacker who alters the header causes a decryption to fail, which is a denial of service and no more: the payload cannot be recovered without the key.
  • It does not replace a MAC. An application that must detect tampering with the header itself should compute a MAC over the whole artefact, header included, and verify it before parsing.

7.3 Rejecting headerless input

Input without a valid header is rejected with E017, never interpreted. This is a deliberate break from pre-4.2.6 material: an earlier release's artefact cannot be distinguished from random data by inspection, and guessing at a format is precisely the failure mode the header exists to prevent.

Material written before the header can still be read, through a compatibility API that synthesises a minimal header and then uses the ordinary path (§12). That is a wrapper around the strict path, not a lenient branch inside it.


8. Attack analysis

7.1 Ciphertext-only

The ciphertext is produced by 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 §6.1 rules out. No practical ciphertext-only attack is known.

7.2 Known-plaintext

An attacker holding (P_i, C_i) pairs can strip the outermost XOR layer to recover the keystream for that session. Three properties limit the damage:

  1. The keystream is bound to the message length. In reference and fast the derivation is parameterised by n = |P|; in turbo and raw the length is hashed into the SHAKE256 seed. Two messages of different lengths therefore yield unrelated keystreams, and recovering one does not enable decryption of another.
  2. The keystream is not invertible. In reference/fast it is the output of a non-invertible mixing pipeline; in turbo/raw it is the output of a hash. Recovering a keystream does not reveal K_user or K_short.
  3. An inner layer remains. The K_long XOR still stands between the attacker and the substituted text. 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.

7.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 tables are static for a given key file.

Determining the tables does not yield:

  • K_long — only ever combined by XOR, never directly exposed;
  • K_short — enters only through the keystream derivation and the SHAKE seed;
  • 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.

7.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.

  • 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 XOR layers combine the data with keystreams that differ per session and per length.

There is no path from input difference to output difference with usable bias. Differential attack has no effective path.

7.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.

7.6 Algebraic attack

Algebraic attacks express the cipher as a system of polynomial equations and solve it. The substitution tables 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 §7.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.8 Mode-specific notes

The analysis above holds for all four modes because the layers an attacker must peel are the same in kind. The differences are quantitative:

  • In raw, there is one fewer structure to peel: the two XOR layers are derived from a single SHAKE256 seed rather than from two independent generators. An attacker who recovers one layer's keystream therefore sits closer to the plaintext than in the other modes.
  • In raw, the ciphertext is compact (1.33x rather than 5.33x), so there is less ciphertext per plaintext byte to work with — which cuts both ways, and is discussed in §9.

9. Quantum algorithms

8.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.

8.2 Grover's algorithm

Grover's algorithm provides a quadratic speed-up for unstructured search, reducing the effective work from S to S^0.5:

S^0.5 ≈ 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.

8.3 Other quantum algorithms

Known quantum attacks target specific structures: finite fields, elliptic curves, lattices, and hash function internals. ChaosCrypt contains none of these. The SHAKE256 keystream used by turbo and raw is a sponge construction, and Grover's algorithm on a 256-bit sponge output offers no advantage beyond the generic square-root bound already accounted for.

No published quantum algorithm offers a practical advantage.


10. What the modes give up

10.0 The three tiers

The four modes fall into three tiers of structural margin:

Tier Modes Layers between ciphertext and substitution
Most reference, fast XOR(long key) then XOR(derived keystream), both over hexadecimal text
Middle turbo XOR(SHAKE stream A) then XOR(SHAKE stream B)
Least raw XOR(long key) then XOR(SHAKE stream), over bytes

turbo and raw are quicker because they stop re-encoding the payload between layers; that is also why they present an attacker with less to unpick. The difference is one of degree: all three keep the substitution tables, the flip pattern, and a keystream bound to the password, the keys and the message length.

raw is the fastest mode by a wide margin — roughly nine times faster than fast at 1 MiB, with ciphertext a quarter the size. It is also the weakest. This section states precisely what is traded, so the choice is informed rather than accidental.

9.1 Fewer layers

reference, fast and turbo present an attacker with:

Base64 → substitution → flip → reversal → XOR(K_long) → XOR(keystream)

raw presents:

substitution → flip → reversal → XOR(keystream₁) → XOR(keystream₂)

Both keystreams come from the same SHAKE256 construction, differing only by a layer index in the seed. An attacker who recovers the outer keystream by known plaintext and knows the layer index therefore faces a second layer from a known family, rather than the independent 4096-nibble K_long XOR the other modes retain. This is the single most significant reduction.

9.2 Base64 no longer randomises the input distribution

In the other modes, Base64 first expands and re-encodes the payload, so the substitution stage sees a flat, alphabet-constrained distribution regardless of the plaintext's structure. In raw, the substitution stage sees the plaintext bytes directly. For structured plaintext — ASCII text, for example — this means the substituted output retains more of the original distribution, which is material an analyst can work with.

9.3 Exact length disclosure

raw ciphertext length equals plaintext length (modulo base64 padding), so it discloses |P| exactly rather than to within |P| mod 3. For most uses this is immaterial; for traffic analysis it is a small additional leak.

Mode Reported length granularity
reference / fast / turbo |P| and |P| mod 3
raw |P| exactly

9.4 What raw does not give up

For the avoidance of doubt, raw still retains:

  • the random substitution bijections (26! × 26! plus digit and padding maps);
  • the conditional case-flip stage;
  • the whole-message reversal;
  • both the 4096-nibble long key and the 512-nibble short key as seed material;
  • a SHAKE256-based keystream bound to password, keys and length;
  • a key space far beyond exhaustive search.

It is a weaker member of a strong family, not a broken cipher. But it is the member to choose when you value throughput over margin, and it should not be the default for anything that matters.

9.5 Recommendation

If you are… Use
Encrypting anything you would be upset to lose fast (default)
Working with existing data from before 4.2.6 reference or fast
Wanting a standardised keystream primitive turbo
Encrypting large volumes where speed dominates and the threat model is mild raw

11. Information leakage

10.1 Message length

Ciphertext length is proportional to plaintext length in every mode. 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.

10.2 Padding class

In reference, fast and turbo, the Base64 padding count (0–3) is encoded in the ciphertext and therefore discloses |P| mod 3. This is two bits, strictly subsumed by §10.1, and reveals nothing about the key or contents. raw does not carry this marker.

10.3 Fixed substitution tables

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 (§7.3) narrows the remaining problem — though it remains infeasible. Rotating key files limits even this.


12. Legacy artefacts

Artefacts written before the header existed carry no header, and are read through a compatibility API rather than by relaxing the reader.

12.1 The wrapper, not a branch

from chaoscrypt import ChaosCrypt

cc = ChaosCrypt(key_file="my.key", key_password="kf-pwd", auto_load=True)
plain = cc.decrypt_legacy(old_ciphertext, "user-pwd")

decrypt_legacy synthesises a minimal header:

{"is_old":true,"old_is_key":false}

prefixes it to the payload unchanged, and then calls the ordinary decrypt. The ordinary path therefore never gains a lenient branch: it still rejects headerless input with E017, and the compatibility API is the only caller that produces the header it needs.

12.2 Which algorithm reads a legacy artefact

When is_old is true, every other field is ignored — including mode, of which there is none. The legacy path tries the bulk-operation implementation first and falls back to the original character pipeline. Both implement the original algorithm, so either can read pre-header material; the fallback costs a second attempt only if the first fails.

Attempt Why
1. fast Same algorithm, quicker
2. reference The original pipeline, if the artefact needs it

12.3 Security properties of the wrapper

  • The payload is not inspected. It is wrapped whole; nothing is inferred from its content.
  • The header is not a weakening. It carries no key material and no privileges; it only tells the reader to use the legacy path.
  • Nothing is written in legacy form. The library only reads old artefacts; its output always carries a full header. wrap_legacy produces a modern artefact, and can be used once to migrate a key file.
  • The strict path is unchanged. A caller that passes headerless input to decrypt still gets E017.

12.4 What is not supported

  • Writing artefacts without a header.
  • Partially trusting a legacy artefact.
  • Reading a legacy artefact through decrypt rather than the compatibility API.

13. Deterministic output

ChaosCrypt has no IV and no salt, in any mode. 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 — a timestamp, for example — 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.


14. Key derivation, per mode

12.1 reference and fast

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 §7.2 exploits.

In fast the same computation is performed with C-level bulk operations. The output is identical; only the cost differs.

12.2 turbo

The keystream is SHAKE256(seed).digest(n) where

seed = domain ‖ len(K_user) ‖ K_user ‖ len(K_short) ‖ K_short
       ‖ K_long ‖ len(n)

Binding the length ensures a keystream recovered for one message is useless for another. Binding all three secrets ensures the stream depends on the full key material. Separate domain tags keep the inner and outer layers independent.

12.3 raw

The keystream is SHAKE256(seed).digest(n) where

seed = domain ‖ layer ‖ len(K_user) ‖ K_user ‖ len(K_short) ‖ K_short
       ‖ K_long ‖ len(n)

The layer field is what keeps the two XOR layers from cancelling. Note that neither turbo nor raw seeds from a nonce, so — like every mode — they are deterministic (§11).

12.4 A note on work factor

None of these is a deliberately slow KDF in the style of PBKDF2, scrypt or Argon2, and none is intended to be. The key file supplies 512 nibbles of independent key material, so the 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.


15. Common misconceptions

"Known plaintext recovers the session keystream, which can then be reused." Recovering a keystream 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 §7.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.

"fast is a weaker mode." It is not. It performs the same arithmetic on the same values and produces the same bytes. Only the Python-level mechanics differ, and the frozen reference vectors are asserted against it so that this cannot quietly stop being true.

"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 §11.

"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.


16. Summary

Properties of 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 in every mode.
  • There are no third-party runtime dependencies.

Properties per mode

Mode Speed (1 MiB) Ciphertext Compatibility Strength
reference 0.334 s 5.33x pre-2.2 ✓ baseline
fast 0.371 s 5.33x pre-2.2 ✓ identical to reference
turbo 0.089 s 5.33x own format stronger primitive
raw 0.036 s 1.33x own format weakest of the four — §9

Things to be aware of

  • Deterministic output for identical inputs (§11).
  • Ciphertext length, and in three modes |P| mod 3, are observable (§10).
  • raw additionally discloses exact plaintext length (§10.3).
  • No independent audit has been performed.

In one sentence: ChaosCrypt is an obfuscation cipher with a strong construction and a deliberately narrow scope; its four modes trade speed against structural margin, and the trade-offs are documented above rather than left for you to discover.

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.


17. 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 and mode 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.


18. 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.