Files
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

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 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, 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_<Detail>_<Code>.
  • 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.