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
869 lines
34 KiB
Markdown
869 lines
34 KiB
Markdown
# 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.
|