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
+404
View File
@@ -0,0 +1,404 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
ChaosCrypt benchmark suite
==========================
Measures the throughput of every public operation in ChaosCrypt.
Run it from the repository root so the package is importable:
python bench/benchmark.py
python bench/benchmark.py --budget 0.05 --repeats 3
python bench/benchmark.py --sizes 64,1024,65536
python bench/benchmark.py --groups Text,Binary
Why this design
---------------
* Every operation is dispatched to a process pool with one worker per CPU
core, so the whole suite completes in a single parallel wave.
* Windows uses the ``spawn`` start method, which means **lambdas and closures
cannot be pickled** and therefore cannot be sent to a worker. Every
benchmark is expressed as a *spec*: a plain, picklable dict describing the
operation and its parameters. Each worker rebuilds the callable locally.
* Inside a worker each task is warmed up, the loop count is auto-calibrated to
fill a small time budget, and the reported figure is the best of N repeats.
That way both fast operations (microseconds) and slow ones (hundreds of
milliseconds) are measured meaningfully.
What is measured
----------------
ChaosCrypt has two distinct costs, and they are reported separately:
* **Key setup** — generating key material, and loading a key file. Dominated by
``os.urandom`` calls for the former and by a 4096-nibble XOR for the latter.
* **Per-message work** — the actual encrypt/decrypt pipelines, which are
linear in message length: Base64, substitution, case flipping, reversal and
two XOR passes.
Output is a set of tables grouped by category, sorted by speed within each
group, plus a summary of wall clock, failures and memory footprint.
See ``docs/benchmark.md`` for the published results and the discussion.
"""
import argparse
import os
import sys
import time
from concurrent.futures import ProcessPoolExecutor, as_completed
# ---------------------------------------------------------------- defaults
DEFAULT_BUDGET = 0.03 # seconds of measurement per task
DEFAULT_REPEATS = 1 # best of N
KB = 1024
MB = 1024 * 1024
GROUPS = ["KeySetup", "Text", "Binary", "File", "Error", "Overhead"]
# =================================================================== timing
def _timeit(call, budget):
"""Warm up, auto-calibrate, and return (seconds_per_op, iterations)."""
call() # warm-up
n = 1
while True:
t0 = time.perf_counter()
for _ in range(n):
call()
dt = time.perf_counter() - t0
if dt >= budget or n >= (1 << 22):
break
n = max(n * 2, int(n * budget / max(dt, 1e-9)))
t0 = time.perf_counter()
for _ in range(n):
call()
return (time.perf_counter() - t0) / n, n
def _payload(size):
"""Deterministic payload, identical in every worker (no RNG involved)."""
seed = b"ChaosCrypt-benchmark-payload-"
return (seed * (size // len(seed) + 2))[:size]
def run_spec(args):
"""Executed inside a worker process. ``args`` = (spec, budget, repeats)."""
spec, budget, repeats = args
sys.path.insert(0, spec["root"])
try:
call, unit_bytes, unit_ops = _build(spec)
best = float("inf")
iters = 0
for _ in range(max(1, repeats)):
sec, n = _timeit(call, budget)
best = min(best, sec)
iters = n
except Exception as e: # noqa: BLE001
return {"name": spec["name"], "group": spec["group"],
"error": f"{type(e).__name__}: {e}"}
res = {"name": spec["name"], "group": spec["group"],
"sec_per_op": best, "ops_per_sec": unit_ops / best, "iters": iters}
if unit_bytes:
res["mb_per_sec"] = (unit_bytes * unit_ops) / best / MB
return res
# =================================================================== builders
def _fixed_core():
"""A ChaosCryptCore with deterministic key material, rebuilt per worker.
Using fixed material keeps measurements comparable between runs, and the
determinism means a warm-up cannot accidentally leave stale state.
"""
import hashlib
from chaoscrypt._core import ChaosCryptCore
def det_hex(n, seed):
out = []
h = hashlib.sha256(seed.encode()).digest()
while len(out) * 64 < n:
h = hashlib.sha256(h).digest()
out.append(h.hex())
return "".join(out)[:n]
c = ChaosCryptCore()
c.upper_mapping = "BCDEFGHIJKLMNOPQRSTUVWXYZA"
c.lower_mapping = "bcdefghijklmnopqrstuvwxyza"
c.digit_mapping = {str(i): ch for i, ch in enumerate("ABCDEFGHIJ")}
c.equal_mapping = {"0": "W", "1": "X", "2": "Z", "3": "Y"}
c.flip_pattern = [1, 0, 1, 0, 0, 1, 0, 0, 1, 0]
c.long_key = det_hex(4096, "bench-long")
c.short_key = det_hex(512, "bench-short")
c.digit_reverse = {v: k for k, v in c.digit_mapping.items()}
c.equal_reverse = {v: k for k, v in c.equal_mapping.items()}
c._build_maps()
c.keys_loaded = True
return c
def _rotating_core():
"""A core that regenerates key material on every call (key-setup cost)."""
from chaoscrypt._core import ChaosCryptCore
core = ChaosCryptCore()
def go():
core.generate_keymaterial()
return go
def _keystream(core, password, length):
"""Pre-derive the password keystream so its cost is excluded from XOR loops."""
return core._derive_final_key(password, length)
def _build(spec):
"""Map a spec to (callable, unit_bytes, unit_ops)."""
op = spec["op"]
sz = spec.get("size", 0)
pwd = spec.get("password", "benchmark-password")
# ---- key setup ----------------------------------------------------
if op == "generate_keymaterial":
return _rotating_core(), None, 1
if op == "load_keys_from_text":
import tempfile
from chaoscrypt import ChaosCrypt
tmp = tempfile.mkdtemp()
path = os.path.join(tmp, "bench.key")
src = ChaosCrypt()
src.create_key(pwd, path)
with open(path, "r") as f:
text = f.read()
from chaoscrypt._core import ChaosCryptCore
fresh = ChaosCryptCore()
return (lambda: fresh.load_keys_from_text(text, pwd)), None, 1
core = _fixed_core()
# ---- text ---------------------------------------------------------
if op == "encrypt_text":
pt = _payload(sz).decode("ascii", "ignore")
return (lambda: core.encrypt_text(pt, pwd)), sz, 1
if op == "decrypt_text":
pt = _payload(sz).decode("ascii", "ignore")
ct = core.encrypt_text(pt, pwd)
return (lambda: core.decrypt_text(ct, pwd)), sz, 1
# ---- binary -------------------------------------------------------
if op == "encrypt_bytes":
data = _payload(sz)
return (lambda: core.encrypt_bytes(data, pwd)), sz, 1
if op == "decrypt_bytes":
data = _payload(sz)
ct = core.encrypt_bytes(data, pwd)
return (lambda: core.decrypt_bytes(ct, pwd)), sz, 1
# ---- internal stages, to show where the time actually goes ---------
if op == "stage_b64encode":
import base64
data = _payload(sz)
return (lambda: base64.b64encode(data)), sz, 1
if op == "stage_substitute":
text = _payload(sz).decode("ascii", "ignore")
return (lambda: core._substitute_letters(text, core.encrypt_map)), sz, 1
if op == "stage_flip":
text = _payload(sz).decode("ascii", "ignore")
return (lambda: core._apply_flip(text)), sz, 1
if op == "stage_xor_long":
text = _payload(sz).decode("ascii", "ignore")
key = core._get_dynamic_key(len(text))
return (lambda: core._xor_encrypt_with_key(text, key)), sz, 1
if op == "stage_derive_key":
return (lambda: core._derive_final_key(pwd, sz)), None, 1
# ---- key file handling --------------------------------------------
if op == "keyfile_encrypt":
blob = _payload(sz).decode("ascii", "ignore")
return (lambda: core._xor_encrypt_data(blob, pwd)), sz, 1
if op == "keyfile_obfuscate":
keys = {
"upper_mapping": core.upper_mapping,
"lower_mapping": core.lower_mapping,
"digit_mapping": core.digit_mapping,
"equal_mapping": core.equal_mapping,
"flip_pattern": core.flip_pattern,
"long_key": core.long_key,
"short_key": core.short_key,
}
return (lambda: core._obfuscate_keys(keys)), None, 1
# ---- overhead -----------------------------------------------------
if op == "random_4096_hex":
return (lambda: core._generate_long_key(4096)), None, 1
if op == "random_512_hex":
return (lambda: core._generate_short_key(512)), None, 1
if op == "shuffle_52":
return (lambda: (core._generate_random_alphabet(),
core._generate_random_alphabet(True))), None, 1
raise ValueError("unknown op: " + op)
# =================================================================== spec table
def make_specs(sizes, groups=None, root="."):
"""Build the task list. ``sizes`` is a list of (label, byte-size)."""
S = []
a = S.append
def add(op, name, group, size=0, extra=None):
spec = {"op": op, "name": name, "group": group, "size": size, "root": root}
if extra:
spec.update(extra)
a(spec)
# Key setup
add("generate_keymaterial", "generate_keymaterial()", "KeySetup")
add("load_keys_from_text", "load_keys_from_text()", "KeySetup")
add("keyfile_obfuscate", "obfuscate_keys()", "KeySetup")
add("keyfile_encrypt", "keyfile XOR wrap [1KB]", "KeySetup", KB)
for label, size in sizes:
add("random_4096_hex", "long key 4096 nibbles", "KeySetup")
break
add("random_512_hex", "short key 512 nibbles", "KeySetup")
add("shuffle_52", "alphabet shuffles (2x)", "KeySetup")
# Text
for label, size in sizes:
add("encrypt_text", f"encrypt_text [{label}]", "Text", size)
add("decrypt_text", f"decrypt_text [{label}]", "Text", size)
# Binary
for label, size in sizes:
add("encrypt_bytes", f"encrypt_bytes [{label}]", "Binary", size)
add("decrypt_bytes", f"decrypt_bytes [{label}]", "Binary", size)
# Internal stages (1 KiB only: they are per-byte costs)
add("stage_b64encode", "stage: Base64 encode [1KB]", "Overhead", KB)
add("stage_substitute", "stage: substitution [1KB]", "Overhead", KB)
add("stage_flip", "stage: case flip [1KB]", "Overhead", KB)
add("stage_xor_long", "stage: XOR long key [1KB]", "Overhead", KB)
add("stage_derive_key", "stage: derive keystream [1KB]", "Overhead", KB)
if groups:
want = {g.lower() for g in groups}
S = [s for s in S if s["group"].lower() in want]
return S
# =================================================================== reporting
def report(results, wall, cores, mem_note=None):
ok = [r for r in results if "error" not in r]
bad = [r for r in results if "error" in r]
groups = {}
for r in ok:
groups.setdefault(r["group"], []).append(r)
for g in GROUPS:
rows = groups.get(g)
if not rows:
continue
rows.sort(key=lambda r: r["sec_per_op"])
print("=" * 96)
print(f" {g}")
print("=" * 96)
print(f" {'operation':42s} {'ops/sec':>15s} {'us/op':>10s} "
f"{'MB/s':>10s} {'iters':>10s}")
print(" " + "-" * 92)
for r in rows:
mbs = f"{r['mb_per_sec']:10.2f}" if "mb_per_sec" in r else f"{'-':>10s}"
print(f" {r['name']:42s} {r['ops_per_sec']:15,.0f} "
f"{r['sec_per_op'] * 1e6:10.3f} {mbs} {r['iters']:10,d}")
print()
if bad:
print("=" * 96)
print(" FAILED")
print("=" * 96)
for r in bad:
print(f" {r['name']:42s} {r['error']}")
print()
print("=" * 96)
print(f" {len(ok)} OK | {len(bad)} failed | wall clock {wall:.2f}s | {cores} cores")
if mem_note:
print(f" {mem_note}")
print("=" * 96)
# =================================================================== main
def main(argv=None):
ap = argparse.ArgumentParser(
description="ChaosCrypt benchmark suite (multiprocess)",
formatter_class=argparse.ArgumentDefaultsHelpFormatter,
)
ap.add_argument("--budget", type=float, default=DEFAULT_BUDGET,
help="seconds of measurement per task")
ap.add_argument("--repeats", type=int, default=DEFAULT_REPEATS,
help="take the best of N measurement rounds")
ap.add_argument("--sizes", default="64,1024",
help="comma-separated payload sizes in bytes")
ap.add_argument("--workers", type=int, default=0,
help="worker processes (0 = one per CPU core)")
ap.add_argument("--groups", default="",
help="comma-separated category filter, e.g. 'Text,Binary'")
args = ap.parse_args(argv)
root = os.getcwd()
sizes = []
for s in args.sizes.split(","):
s = s.strip()
if not s:
continue
n = int(s)
label = f"{n}B" if n < KB else (f"{n // KB}KB" if n < MB else f"{n // MB}MB")
sizes.append((label, n))
if not sizes:
ap.error("no valid --sizes given")
groups = [g.strip() for g in args.groups.split(",") if g.strip()]
specs = make_specs(sizes, groups or None, root=root)
if not specs:
ap.error("no benchmarks selected for the given --groups / --sizes")
cores = os.cpu_count() or 4
workers = args.workers or min(cores, len(specs))
print(f"[*] ChaosCrypt benchmark: {len(specs)} tasks / {workers} workers "
f"({cores} cores)", flush=True)
print(f"[*] budget {args.budget}s x {args.repeats} repeats, "
f"sizes {[l for l, _ in sizes]}"
+ (f", groups {groups}" if groups else "") + "\n", flush=True)
t0 = time.perf_counter()
results = []
with ProcessPoolExecutor(max_workers=workers) as ex:
futs = [ex.submit(run_spec, (s, args.budget, args.repeats)) for s in specs]
for i, f in enumerate(as_completed(futs), 1):
results.append(f.result())
print(f"\r {i}/{len(specs)}", end="", flush=True)
wall = time.perf_counter() - t0
print(f"\n[*] wall clock: {wall:.2f}s\n")
note = None
try:
import resource # POSIX only
ru = resource.getrusage(resource.RUSAGE_SELF).ru_maxrss
note = f"peak RSS {ru / 1024:.1f} MB"
except Exception:
pass
report(results, wall, cores, note)
return 0
if __name__ == "__main__":
sys.exit(main())