# Changelog All notable changes to this project are documented in this file. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/). --- ## [4.2.6] — 2026-09-27 Self-describing artefacts, a byte pipeline worth using, and a large performance pass. This release changes the on-disk format incompatibly and is the first version intended to be deployed rather than experimented with. ### Added - **Self-describing header on every artefact.** Each key file and ciphertext now begins with a magic value, two fixed markers, and a complete JSON configuration record that states how the payload was produced. A reader never has to be told the mode, the encoding or the intermediate representation: it reads them. See [docs/FORMAT.md](docs/FORMAT.md). ``` 69CES 385aeff1f4179a744c8fb0c5ae4702d325f6230d059f4251135c2536409dee93 {"alg":"chaoscrypt","kind":"ciphertext","mode":"turbo","out":"hex",...} 2025ea4e4b4b93803f2ccadeaf318d1957ce42ff5409410f660348be96a4c0f2 ``` - **Two new error codes**, for the two ways a header can be wrong: - `E017 MissingMagicHeader` — the input is not a CES artefact at all - `E018 MalformedHeader` — a marker is missing, the JSON is unusable, a required field is absent, or `kind` does not match - **Byte pipeline for `turbo` and `raw`.** Between the XOR layers the payload is now carried as raw bytes rather than hexadecimal text. This removes a doubling of the payload at each layer: expansion drops from **5.33x to 2.00x** and throughput rises by roughly **4x**. The old behaviour is still available as `mid="hex"`. - **Selectable output encoding** for `turbo` and `raw`: `hex` (2.00x) or `base64` (1.33x). - **Legacy compatibility API**, for artefacts written before the header existed: - `wrap_legacy(text, is_key)` — synthesise a minimal header and return a well-formed artefact - `decrypt_legacy(text, password, is_key)` — read an artefact that may predate the header - `decrypt_legacy_auto(text, password)` — as above, probing whether the input is a key file or a ciphertext - `load_legacy_keys(text, key_password)` — load a pre-header key file Legacy support is a *wrapper* around the ordinary path, never a lenient branch inside it: the payload is given a header and then read normally, so the strict path stays strict. - **Frozen reference vectors** covering eleven cases across every mode, encoding and intermediate representation, plus five error cases. - **Documentation**: `docs/FORMAT.md` as the normative format specification, `docs/benchmark.md` with measured throughput and the profiling behind it, and a rewritten `SECURITY.md` covering the four modes. ### Changed - **Default mode is `fast`**, which is byte-for-byte compatible with the original algorithm and roughly 30x quicker. - **Substitution, case flipping and the printable fold** run through `bytes.translate` over precomputed 256-entry tables. - **XOR layers** use a single big-integer operation instead of a per-byte loop with `%02x` formatting. - **Keystream derivation** caches the length-independent base material, and the expansion uses cached translation tables rather than `str.join` over a generator. - **`_get_dynamic_key`** repeats the long key by multiplication rather than `key += long_key` in a loop. The loop version was quadratic: covering a 5.6 MB intermediate took 866 ms and dominated the 1 MiB timings. The same work now takes about 3 ms, with identical output. - **`_derive_final_key`** decodes only the prefix of the hex round trip that the output actually consumes, rather than the whole thing. - **The decrypt path** no longer copies or scans the full artefact: a redundant `strip()`, a full-string `int(payload, 16)` validation, and three whole-string slices in `strip_header` were all removed. Decryption throughput roughly doubled at 512 KiB, from 34 MB/s to 87 MB/s. - **Version raised to 4.2.6.** ### Fixed 1. Key material derivation is no longer quadratic. `_get_dynamic_key` was the worst offender, and `_expand_keystream_slow` shared the pattern. 2. Two hex-intermediate pipelines were asymmetric, so a `turbo` or `raw` artefact produced with `mid="hex"` could not be read back. Both are now exact mirrors. 3. `change_key_password` and `export_key_text` wrote artefacts without a header, producing files this library then refused to load. 4. The constructor accepted `encoding="base64"` while the header records `out="base"`. Both spellings are now accepted, so a caller can read a header and pass the value straight back in. 5. A payload that is not valid hexadecimal now reports `E010` (MalformedCiphertext) rather than `E011` (DecryptionFailed). The distinction matters: the first means the artefact is malformed, the second means the password or key is wrong. 6. The TUI's encoding menu referenced a missing translation and displayed the key name instead of the description. ### Security - **Format break from pre-4.2.6 artefacts.** Headerless input is rejected with `E017`; use the compatibility API to read old material. Old scripts cannot read new artefacts. This is deliberate and documented, not an oversight. - **`fast` is not a weaker mode**: it performs the same arithmetic and produces the same bytes. The test suite asserts this against the frozen vectors. - **`raw` with a hex intermediate is the weakest configuration** and is documented as such: fewer structural layers stand between an attacker and the substituted text. - The header is metadata. It adds no secrecy and is not authenticated; an application that must detect header tampering should MAC the whole artefact. ### Performance Measured on the machine described in [docs/benchmark.md](docs/benchmark.md), hex output, keystream cache warm. | Mode / mid | 64 KiB | 1 MiB | 16 MiB | 128 MiB | 1024 MiB | |---|---:|---:|---:|---:|---:| | `raw` bt enc | 26.9 | 57.3 | 63.4 | 59.4 | 47.9 | | `raw` bt dec | 60.6 | 61.0 | 69.0 | 64.5 | 31.7 | | `raw` hex enc | 20.7 | 19.3 | 18.9 | 18.2 | — | | `raw` hex dec | 20.2 | 21.8 | 22.7 | 18.0 | — | Throughput in MB/s. It holds steady across four orders of magnitude, which is what a linear algorithm looks like. For scale, the original implementation managed **0.08 MB/s** — about twelve seconds per megabyte. ### Compatibility - `reference` and `fast` produce payloads byte-for-byte identical to the original algorithm; only the header is new. - `turbo` and `raw` define their own formats, and their payloads differ by `out` and `mid`. An artefact is read with the parameters it carries, and there is no fallback between them. - The key file format carries a header but is otherwise unchanged. - Artefacts written before the header existed are readable only through the compatibility API. --- ## [2.1.6] — 2026-09-27 Packaging release. The algorithm is unchanged; this version restructures the project as a distributable library. ### Added - Bilingual interactive TUI, English and Chinese, switchable at runtime. - Full command line interface: `keygen`, `encrypt`, `decrypt`, `file`, `info`, `chpwd`, `tui`. - Unified error hierarchy: sixteen named types rendering as `ChaosCrypt_ERR__`. - Binary and file support. - Key management helpers: `change_key_password`, `export_key_text`, `load_from_text`. - Packaging: `pyproject.toml`, `setup.py` shim, `MANIFEST.in`, `py.typed`. ### Fixed 1. The `-p` and `-P` option groups both registered `--pwd`, so the CLI could not start at all. 2. A wrong key file password was reported as file corruption (`E002`). 3. `export_key_text` produced key material without loading it into the instance. 4. **Non-hexadecimal input was accepted as ciphertext and silently decrypted into garbage**, making corruption indistinguishable from success. 5. The TUI failed under piped input, because `getpass` requires a TTY. 6. After generating a key file, the TUI kept looking at the default file name. --- ## [2.0.0] — Original release The original single-file implementation of the ChaosCrypt cipher. ### Added - Random system key generation. - Password-protected key file wrapping. - Layered encryption: Base64, substitution, conditional case flipping, whole-message reversal, and two XOR stages. - Interactive menu for encryption, decryption and key management. [4.2.6]: https://git.dvscloud.net/dvs/ChaosCrypt/releases/tag/v4.2.6 [2.1.6]: https://git.dvscloud.net/dvs/ChaosCrypt/releases/tag/v2.1.6 [2.0.0]: https://git.dvscloud.net/dvs/ChaosCrypt/releases/tag/v2.0.0