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
204 lines
8.5 KiB
Markdown
204 lines
8.5 KiB
Markdown
# 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
|
|
<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](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.
|
|
|
|
[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
|