Files
ChaosCrypt/chaoscrypt/tests/test_vectors_strict.py
T
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

295 lines
12 KiB
Python

# -*- 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