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
This commit is contained in:
dvs
2026-09-27 22:06:34 +08:00
parent 24a36d6fb4
commit dd49043171
25 changed files with 5348 additions and 852 deletions
+80 -4
View File
@@ -15,7 +15,8 @@ import os
import sys
from typing import Optional
from . import DEFAULT_KEY_FILE, __version__, ChaosCrypt
from . import (DEFAULT_KEY_FILE, __version__, ChaosCrypt, MODES,
DEFAULT_MODE, ENCODINGS, DEFAULT_ENCODING)
from .errors import ChaosCryptError
from .i18n import DEFAULT_LANG, LANG_NAMES, t
@@ -135,10 +136,14 @@ class TUI:
"""Menu-driven bilingual interface over :class:`~chaoscrypt.ChaosCrypt`."""
def __init__(self, lang: str = DEFAULT_LANG,
key_file: str = DEFAULT_KEY_FILE) -> None:
key_file: str = DEFAULT_KEY_FILE,
mode: str = DEFAULT_MODE,
encoding: str = DEFAULT_ENCODING) -> None:
self.lang = lang if lang in LANG_NAMES else DEFAULT_LANG
self.key_file = key_file
self.cc = ChaosCrypt()
self.mode = mode if mode in MODES else DEFAULT_MODE
self.encoding = encoding if encoding in ENCODINGS else DEFAULT_ENCODING
self.cc = ChaosCrypt(mode=self.mode, encoding=self.encoding)
self.key_password: Optional[str] = None
# ------------------------------------------------------------------ view
@@ -162,7 +167,7 @@ class TUI:
if self.cc.loaded
else c("[ ] " + self._tr("no_key_loaded"), "red")
)
print(f"\n{state} {c(shown, 'dim')}")
print(f"\n{state} {c(shown, 'dim')} {c('[' + self.mode + ']', 'yellow')}")
def _print_error(self, exc: Exception) -> None:
"""Render a unified error, with a hint where one applies."""
@@ -190,6 +195,8 @@ class TUI:
("7", "menu_keyinfo"),
("8", "menu_chpwd"),
("9", "menu_lang"),
("m", "menu_mode"),
("e", "menu_encoding"),
("a", "menu_about"),
("q", "menu_quit"),
]
@@ -361,6 +368,8 @@ class TUI:
("info_short_key",
f"{info['short_key_length']} {self._tr('characters')}"),
("info_loaded", self._tr("yes")),
("info_mode", self.mode),
("info_encoding", self.encoding),
]
print()
print(c(_rule(), "dim"))
@@ -405,6 +414,69 @@ class TUI:
self.lang = choice
print(c(f" -> {LANG_NAMES[self.lang]}", "green"))
def action_mode(self) -> None:
"""Switch the performance mode of the active core."""
print()
for i, name in enumerate(MODES, 1):
mark = "*" if name == self.mode else " "
desc = self._tr(f"mode_{name}_desc")
print(f" {c('[' + str(i) + ']', 'cyan')} {mark} {desc}")
default_index = str(MODES.index(self.mode) + 1)
choice = _ask(self._tr("mode_prompt"), default_index)
try:
idx = int(choice) - 1
if 0 <= idx < len(MODES):
self.mode = MODES[idx]
except ValueError:
if choice in MODES:
self.mode = choice
# Rebuild the core so the new mode takes effect, then reload the key
# if one was already loaded so the user does not have to re-enter the
# password.
was_loaded = self.cc.loaded
path = self.cc.key_file or self.key_file
pwd = self.key_password
self.cc = ChaosCrypt(mode=self.mode, encoding=self.encoding)
if was_loaded and path and pwd:
try:
self.cc.load(path, pwd)
except ChaosCryptError:
pass
print(c(f" -> {self._tr('mode_changed')} {self.mode}", "green"))
def action_encoding(self) -> None:
"""Switch the output encoding (turbo and raw only)."""
print()
for i, name in enumerate(ENCODINGS, 1):
mark = "*" if name == self.encoding else " "
desc = self._tr(f"encoding_{name}_desc")
print(f" {c('[' + str(i) + ']', 'cyan')} {mark} {desc}")
print(c(" " + self._tr("encoding_note"), "dim"))
default_index = str(ENCODINGS.index(self.encoding) + 1)
choice = _ask(self._tr("encoding_prompt"), default_index)
try:
idx = int(choice) - 1
if 0 <= idx < len(ENCODINGS):
self.encoding = ENCODINGS[idx]
except ValueError:
if choice in ENCODINGS:
self.encoding = choice
# Rebuild so the new encoding applies, then restore the loaded key.
was_loaded = self.cc.loaded
path = self.cc.key_file or self.key_file
pwd = self.key_password
self.cc = ChaosCrypt(mode=self.mode, encoding=self.encoding)
if was_loaded and path and pwd:
try:
self.cc.load(path, pwd)
except ChaosCryptError:
pass
print(c(f" -> {self._tr('encoding_changed')} {self.encoding}", "green"))
def action_about(self) -> None:
print()
print(c(self._tr("about_body"), "cyan"))
@@ -439,6 +511,10 @@ class TUI:
self.action_chpwd()
elif choice == "9":
self.action_lang()
elif choice in ("m", "mode"):
self.action_mode()
elif choice in ("e", "encoding"):
self.action_encoding()
elif choice in ("a", "about"):
self.action_about()
elif choice in ("q", "quit", "exit"):