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
34 KiB
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 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 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 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. 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 |
6.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.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
ksumis 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:
- The keystream is bound to the message length. In
referenceandfastthe derivation is parameterised byn = |P|; inturboandrawthe 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. - The keystream is not invertible. In
reference/fastit is the output of a non-invertible mixing pipeline; inturbo/rawit is the output of a hash. Recovering a keystream does not revealK_userorK_short. - An inner layer remains. The
K_longXOR 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.
7.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.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_legacyproduces 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
decryptstill getsE017.
12.4 What is not supported
- Writing artefacts without a header.
- Partially trusting a legacy artefact.
- Reading a legacy artefact through
decryptrather 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:
- 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 §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). rawadditionally 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.