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:
@@ -0,0 +1,294 @@
|
||||
# -*- coding: utf-8 -*-
|
||||
"""
|
||||
Strict reference-vector tests.
|
||||
|
||||
ChaosCrypt is a self-designed construction, so unlike AES or SHA-3 there are no
|
||||
FIPS or RFC vectors to check it against. What can be checked is that the format
|
||||
and the algorithm do not drift: the vectors in
|
||||
``vectors/chaoscrypt_reference.json`` are generated from the implementation and
|
||||
then frozen. If anything changes -- a substitution table, a bit operation, a
|
||||
loop bound, the header layout, an encoding -- these tests fail.
|
||||
|
||||
Every artefact now carries a self-describing header, so each case is checked
|
||||
for three things: the header is present and consistent, the ciphertext matches
|
||||
the frozen value exactly, and the payload round-trips.
|
||||
"""
|
||||
import pytest
|
||||
|
||||
from chaoscrypt._core import ChaosCryptCore
|
||||
from chaoscrypt.errors import ChaosCryptError
|
||||
from chaoscrypt._header import (
|
||||
MAGIC, BEGIN_MARKER, END_MARKER, read_header, strip_header,
|
||||
MIDS, OUTS, KIND_CIPHERTEXT,
|
||||
)
|
||||
|
||||
from ._vectors import available, load
|
||||
|
||||
VECTOR_NAME = "chaoscrypt_reference"
|
||||
|
||||
|
||||
@pytest.fixture(scope="module")
|
||||
def vectors():
|
||||
return load(VECTOR_NAME)
|
||||
|
||||
|
||||
def _core_from(km, mode="fast", enc="hex", mid="bt"):
|
||||
"""Build a ChaosCryptCore preloaded with fixed key material."""
|
||||
c = ChaosCryptCore(mode, "hash", enc, mid)
|
||||
c.upper_mapping = km["upper_mapping"]
|
||||
c.lower_mapping = km["lower_mapping"]
|
||||
c.digit_mapping = km["digit_mapping"]
|
||||
c.equal_mapping = km["equal_mapping"]
|
||||
c.flip_pattern = km["flip_pattern"]
|
||||
c.long_key = km["long_key"]
|
||||
c.short_key = km["short_key"]
|
||||
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
|
||||
|
||||
|
||||
@pytest.fixture(scope="module")
|
||||
def core(vectors):
|
||||
return _core_from(vectors["key_material"])
|
||||
|
||||
|
||||
def _per_case_core(case, km):
|
||||
"""A core configured the way the case was produced."""
|
||||
return _core_from(km,
|
||||
mode=case.get("mode", "fast"),
|
||||
enc=case.get("out", "hex"),
|
||||
mid=case.get("mid", "bt"))
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Vector file integrity
|
||||
# ---------------------------------------------------------------------------
|
||||
class TestVectorFile:
|
||||
def test_vector_file_is_present(self):
|
||||
assert VECTOR_NAME in available()
|
||||
|
||||
def test_required_sections_exist(self, vectors):
|
||||
for key in ("key_material", "passwords", "cases",
|
||||
"error_cases", "key_material_properties"):
|
||||
assert key in vectors, f"missing section: {key}"
|
||||
|
||||
def test_long_key_is_4096_nibbles(self, vectors):
|
||||
assert len(vectors["key_material"]["long_key"]) == 4096
|
||||
|
||||
def test_short_key_is_512_nibbles(self, vectors):
|
||||
assert len(vectors["key_material"]["short_key"]) == 512
|
||||
|
||||
def test_keys_are_valid_hex(self, vectors):
|
||||
int(vectors["key_material"]["long_key"], 16)
|
||||
int(vectors["key_material"]["short_key"], 16)
|
||||
|
||||
def test_case_ids_are_unique(self, vectors):
|
||||
ids = [c["id"] for c in vectors["cases"]]
|
||||
assert len(ids) == len(set(ids))
|
||||
|
||||
def test_case_modes_are_known(self, vectors):
|
||||
from chaoscrypt import MODES
|
||||
for case in vectors["cases"]:
|
||||
assert case.get("mode", "fast") in MODES, case["id"]
|
||||
|
||||
def test_case_mids_and_outs_are_known(self, vectors):
|
||||
for case in vectors["cases"]:
|
||||
assert case.get("mid", "bt") in MIDS, case["id"]
|
||||
assert case.get("out", "hex") in OUTS, case["id"]
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Key material invariants
|
||||
# ---------------------------------------------------------------------------
|
||||
class TestKeyMaterialInvariants:
|
||||
def test_upper_mapping_is_a_bijection(self, vectors):
|
||||
m = vectors["key_material"]["upper_mapping"]
|
||||
assert len(m) == 26
|
||||
assert sorted(m) == sorted("ABCDEFGHIJKLMNOPQRSTUVWXYZ")
|
||||
|
||||
def test_lower_mapping_is_a_bijection(self, vectors):
|
||||
m = vectors["key_material"]["lower_mapping"]
|
||||
assert len(m) == 26
|
||||
assert sorted(m) == sorted("abcdefghijklmnopqrstuvwxyz")
|
||||
|
||||
def test_digit_mapping_covers_all_digits(self, vectors):
|
||||
m = vectors["key_material"]["digit_mapping"]
|
||||
assert sorted(m.keys()) == sorted("0123456789")
|
||||
assert len(set(m.values())) == 10
|
||||
|
||||
def test_equal_mapping_covers_padding_counts(self, vectors):
|
||||
m = vectors["key_material"]["equal_mapping"]
|
||||
assert sorted(m.keys()) == ["0", "1", "2", "3"]
|
||||
assert len(set(m.values())) == 4
|
||||
|
||||
def test_flip_pattern_is_ten_bits(self, vectors):
|
||||
p = vectors["key_material"]["flip_pattern"]
|
||||
assert len(p) == 10
|
||||
assert all(b in (0, 1) for b in p)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Header conformance of every frozen case
|
||||
# ---------------------------------------------------------------------------
|
||||
class TestFrozenHeaders:
|
||||
def test_every_case_starts_with_the_magic(self, vectors):
|
||||
magic = MAGIC.decode()
|
||||
for case in vectors["cases"]:
|
||||
assert case["ciphertext"].startswith(magic), case["id"]
|
||||
|
||||
def test_every_case_carries_both_markers(self, vectors):
|
||||
for case in vectors["cases"]:
|
||||
ct = case["ciphertext"]
|
||||
assert BEGIN_MARKER in ct, case["id"]
|
||||
assert END_MARKER in ct, case["id"]
|
||||
|
||||
def test_every_case_header_parses(self, vectors):
|
||||
for case in vectors["cases"]:
|
||||
cfg = read_header(case["ciphertext"])
|
||||
assert cfg["kind"] == KIND_CIPHERTEXT, case["id"]
|
||||
|
||||
def test_header_mode_matches_the_case(self, vectors):
|
||||
for case in vectors["cases"]:
|
||||
cfg = read_header(case["ciphertext"])
|
||||
assert cfg["mode"] == case.get("mode", "fast"), case["id"]
|
||||
|
||||
def test_header_mid_matches_the_case(self, vectors):
|
||||
"""The header's mid must match what the case says, or hex for the
|
||||
character pipelines, which have no mid of their own."""
|
||||
for case in vectors["cases"]:
|
||||
cfg = read_header(case["ciphertext"])
|
||||
mode = case.get("mode", "fast")
|
||||
if mode in ("reference", "fast"):
|
||||
assert cfg["mid"] == "hex", case["id"]
|
||||
else:
|
||||
assert cfg["mid"] == case.get("mid", "bt"), case["id"]
|
||||
|
||||
def test_header_out_matches_the_case(self, vectors):
|
||||
for case in vectors["cases"]:
|
||||
cfg = read_header(case["ciphertext"])
|
||||
mode = case.get("mode", "fast")
|
||||
if mode in ("reference", "fast"):
|
||||
assert cfg["out"] == "hex", case["id"]
|
||||
else:
|
||||
assert cfg["out"] == case.get("out", "hex"), case["id"]
|
||||
|
||||
def test_reference_and_fast_always_report_hex(self, vectors):
|
||||
"""The character pipelines ignore mid and always use hex."""
|
||||
for case in vectors["cases"]:
|
||||
if case.get("mode") in ("reference", "fast"):
|
||||
cfg = read_header(case["ciphertext"])
|
||||
assert cfg["mid"] == "hex", case["id"]
|
||||
assert cfg["out"] == "hex", case["id"]
|
||||
|
||||
def test_payload_is_not_empty(self, vectors):
|
||||
for case in vectors["cases"]:
|
||||
assert strip_header(case["ciphertext"]), case["id"]
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# The frozen ciphertexts themselves
|
||||
# ---------------------------------------------------------------------------
|
||||
class TestFrozenVectors:
|
||||
def test_encryption_reproduces_frozen_ciphertext(self, vectors):
|
||||
"""Encrypting the recorded plaintext must yield the recorded artefact."""
|
||||
km = vectors["key_material"]
|
||||
pwd = vectors["passwords"]["user_password"]
|
||||
failures = []
|
||||
for case in vectors["cases"]:
|
||||
c = _per_case_core(case, km)
|
||||
got = c.encrypt_text(case["plaintext"], pwd)
|
||||
if got != case["ciphertext"]:
|
||||
failures.append(
|
||||
f"{case['id']}:\n expected {case['ciphertext'][:80]}\n"
|
||||
f" got {got[:80]}"
|
||||
)
|
||||
assert not failures, (
|
||||
"frozen vectors no longer match -- format or algorithm changed:\n"
|
||||
+ "\n".join(failures)
|
||||
)
|
||||
|
||||
def test_decryption_round_trips(self, vectors):
|
||||
km = vectors["key_material"]
|
||||
pwd = vectors["passwords"]["user_password"]
|
||||
for case in vectors["cases"]:
|
||||
c = _per_case_core(case, km)
|
||||
got = c.decrypt_text(case["ciphertext"], pwd)
|
||||
assert got == case["plaintext"], case["id"]
|
||||
|
||||
def test_encryption_is_deterministic(self, vectors):
|
||||
km = vectors["key_material"]
|
||||
pwd = vectors["passwords"]["user_password"]
|
||||
for case in vectors["cases"]:
|
||||
c = _per_case_core(case, km)
|
||||
a = c.encrypt_text(case["plaintext"], pwd)
|
||||
b = c.encrypt_text(case["plaintext"], pwd)
|
||||
assert a == b, f"{case['id']} is not deterministic"
|
||||
|
||||
def test_wrong_password_does_not_reproduce_plaintext(self, core, vectors):
|
||||
case = vectors["cases"][0]
|
||||
try:
|
||||
got = core.decrypt_text(case["ciphertext"], "not-the-password")
|
||||
except ChaosCryptError:
|
||||
return
|
||||
assert got != case["plaintext"]
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Error behaviour
|
||||
# ---------------------------------------------------------------------------
|
||||
class TestFrozenErrorCases:
|
||||
def test_error_cases_raise_expected_codes(self, core, vectors):
|
||||
failures = []
|
||||
for case in vectors["error_cases"]:
|
||||
try:
|
||||
if case["kind"] == "encrypt":
|
||||
core.encrypt_text(case["plaintext"], case["password"])
|
||||
else:
|
||||
core.decrypt_text(case["ciphertext"], case["password"])
|
||||
except ChaosCryptError as e:
|
||||
if e.code != case["expect_code"]:
|
||||
failures.append(
|
||||
f"{case['id']}: expected {case['expect_code']}, got {e.code}"
|
||||
)
|
||||
else:
|
||||
failures.append(
|
||||
f"{case['id']}: expected {case['expect_code']}, no error raised"
|
||||
)
|
||||
assert not failures, "\n".join(failures)
|
||||
|
||||
def test_headerless_input_is_rejected(self, core, vectors):
|
||||
"""The deliberate break from pre-4.2.6 material."""
|
||||
with pytest.raises(ChaosCryptError) as ei:
|
||||
core.decrypt_text("72370655031311011c111f261365172716020b69", "pw")
|
||||
assert ei.value.code == "E017"
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Known-answer tests for the building blocks
|
||||
# ---------------------------------------------------------------------------
|
||||
class TestKnownAnswers:
|
||||
def test_digit_mapping_encode(self, core, vectors):
|
||||
kat = next(k for k in vectors["known_answer_tests"]
|
||||
if k["id"] == "digit_mapping_encode")
|
||||
assert core._encode_digit(kat["input"]) == kat["expected"]
|
||||
|
||||
def test_digit_mapping_round_trip(self, core, vectors):
|
||||
kat = next(k for k in vectors["known_answer_tests"]
|
||||
if k["id"] == "digit_mapping_encode")
|
||||
assert core._decode_digit(kat["expected"]) == kat["input"]
|
||||
|
||||
def test_equal_mapping_values(self, vectors):
|
||||
kat = next(k for k in vectors["known_answer_tests"]
|
||||
if k["id"] == "equal_mapping_values")
|
||||
assert vectors["key_material"]["equal_mapping"] == kat["expected"]
|
||||
|
||||
def test_substitution_round_trip(self, core):
|
||||
sample = "ABCXYZabcxyz"
|
||||
subbed = core._substitute_letters(sample, core.encrypt_map)
|
||||
assert core._substitute_letters(subbed, core.decrypt_map) == sample
|
||||
|
||||
def test_case_flip_is_its_own_inverse(self, core):
|
||||
sample = "AbCdEfGhIjKlMnOp"
|
||||
assert core._apply_flip(core._apply_flip(sample)) == sample
|
||||
Reference in New Issue
Block a user