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
8.5 KiB
Changelog
All notable changes to this project are documented in this file.
The format follows Keep a Changelog, and this project adheres to Semantic Versioning.
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.
69CES 385aeff1f4179a744c8fb0c5ae4702d325f6230d059f4251135c2536409dee93 {"alg":"chaoscrypt","kind":"ciphertext","mode":"turbo","out":"hex",...} 2025ea4e4b4b93803f2ccadeaf318d1957ce42ff5409410f660348be96a4c0f2 <payload> -
Two new error codes, for the two ways a header can be wrong:
E017 MissingMagicHeader— the input is not a CES artefact at allE018 MalformedHeader— a marker is missing, the JSON is unusable, a required field is absent, orkinddoes not match
-
Byte pipeline for
turboandraw. 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 asmid="hex". -
Selectable output encoding for
turboandraw:hex(2.00x) orbase64(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 artefactdecrypt_legacy(text, password, is_key)— read an artefact that may predate the headerdecrypt_legacy_auto(text, password)— as above, probing whether the input is a key file or a ciphertextload_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.mdas the normative format specification,docs/benchmark.mdwith measured throughput and the profiling behind it, and a rewrittenSECURITY.mdcovering 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.translateover precomputed 256-entry tables. -
XOR layers use a single big-integer operation instead of a per-byte loop with
%02xformatting. -
Keystream derivation caches the length-independent base material, and the expansion uses cached translation tables rather than
str.joinover a generator. -
_get_dynamic_keyrepeats the long key by multiplication rather thankey += long_keyin 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_keydecodes 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-stringint(payload, 16)validation, and three whole-string slices instrip_headerwere all removed. Decryption throughput roughly doubled at 512 KiB, from 34 MB/s to 87 MB/s. -
Version raised to 4.2.6.
Fixed
- Key material derivation is no longer quadratic.
_get_dynamic_keywas the worst offender, and_expand_keystream_slowshared the pattern. - Two hex-intermediate pipelines were asymmetric, so a
turboorrawartefact produced withmid="hex"could not be read back. Both are now exact mirrors. change_key_passwordandexport_key_textwrote artefacts without a header, producing files this library then refused to load.- The constructor accepted
encoding="base64"while the header recordsout="base". Both spellings are now accepted, so a caller can read a header and pass the value straight back in. - A payload that is not valid hexadecimal now reports
E010(MalformedCiphertext) rather thanE011(DecryptionFailed). The distinction matters: the first means the artefact is malformed, the second means the password or key is wrong. - 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. fastis not a weaker mode: it performs the same arithmetic and produces the same bytes. The test suite asserts this against the frozen vectors.rawwith 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, 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
referenceandfastproduce payloads byte-for-byte identical to the original algorithm; only the header is new.turboandrawdefine their own formats, and their payloads differ byoutandmid. 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_<Detail>_<Code>. - Binary and file support.
- Key management helpers:
change_key_password,export_key_text,load_from_text. - Packaging:
pyproject.toml,setup.pyshim,MANIFEST.in,py.typed.
Fixed
- The
-pand-Poption groups both registered--pwd, so the CLI could not start at all. - A wrong key file password was reported as file corruption (
E002). export_key_textproduced key material without loading it into the instance.- Non-hexadecimal input was accepted as ciphertext and silently decrypted into garbage, making corruption indistinguishable from success.
- The TUI failed under piped input, because
getpassrequires a TTY. - 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.