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

869 lines
34 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`](https://cryptography.io). 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` |
### 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](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](#12-legacy-artefacts)). 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.**
### 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
```python
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:
```json
{"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`](LICENSE) for the full text.