Files
ChaosCrypt/chaoscrypt/errors.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

160 lines
6.2 KiB
Python

"""
Unified error types for ChaosCrypt.
Every failure raised by this library is a subclass of :class:`ChaosCryptError`,
and every instance renders as::
ChaosCrypt_ERR_<short description>_<code>
The machine-readable ``code`` attribute (``E001`` … ``E016``) is stable and is
safe to branch on; the human-readable portion is documentation only and may be
reworded between minor releases.
Catching :class:`ChaosCryptError` is sufficient to handle every error the
library can raise.
"""
from __future__ import annotations
__all__ = [
"ChaosCryptError",
"ChaosCrypt_ERR_KeyFileNotFound_E001",
"ChaosCrypt_ERR_KeyFileCorrupted_E002",
"ChaosCrypt_ERR_KeyPasswordIncorrect_E003",
"ChaosCrypt_ERR_KeyNotLoaded_E004",
"ChaosCrypt_ERR_KeyFileExists_E005",
"ChaosCrypt_ERR_EmptyPassword_E006",
"ChaosCrypt_ERR_PasswordMismatch_E007",
"ChaosCrypt_ERR_EmptyPlaintext_E008",
"ChaosCrypt_ERR_EmptyCiphertext_E009",
"ChaosCrypt_ERR_MalformedCiphertext_E010",
"ChaosCrypt_ERR_DecryptionFailed_E011",
"ChaosCrypt_ERR_EncodingFailed_E012",
"ChaosCrypt_ERR_InvalidArgument_E013",
"ChaosCrypt_ERR_FileReadFailed_E014",
"ChaosCrypt_ERR_FileWriteFailed_E015",
"ChaosCrypt_ERR_UnsupportedKeyVersion_E016",
"ChaosCrypt_ERR_MissingMagicHeader_E017",
"ChaosCrypt_ERR_MalformedHeader_E018",
]
class ChaosCryptError(Exception):
"""Base class for every error raised by ChaosCrypt.
Attributes:
detail: Human-readable description of what went wrong.
code: Stable machine-readable code, e.g. ``"E003"``.
message: The fully rendered ``ChaosCrypt_ERR_<detail>_<code>`` string.
"""
#: Default machine-readable code; overridden by subclasses.
CODE = "E000"
#: Default human-readable detail; overridden by subclasses.
DETAIL = "UnknownError"
def __init__(self, detail: str | None = None, code: str | None = None):
self.detail = detail if detail is not None else self.DETAIL
self.code = code if code is not None else self.CODE
self.message = f"ChaosCrypt_ERR_{self.detail}_{self.code}"
super().__init__(self.message)
def __str__(self) -> str: # pragma: no cover - trivial
return self.message
def __repr__(self) -> str: # pragma: no cover - trivial
return f"{type(self).__name__}({self.message!r})"
def _define(name: str, detail: str, code: str, doc: str) -> type:
"""Create a named ``ChaosCryptError`` subclass."""
return type(
name,
(ChaosCryptError,),
{"DETAIL": detail, "CODE": code, "__doc__": doc},
)
# ---------------------------------------------------------------------------
# Named error types
# ---------------------------------------------------------------------------
ChaosCrypt_ERR_KeyFileNotFound_E001 = _define(
"ChaosCrypt_ERR_KeyFileNotFound_E001", "KeyFileNotFound", "E001",
"The requested key file does not exist.",
)
ChaosCrypt_ERR_KeyFileCorrupted_E002 = _define(
"ChaosCrypt_ERR_KeyFileCorrupted_E002", "KeyFileCorrupted", "E002",
"The key file could not be parsed (truncated, altered, or not a "
"ChaosCrypt key file).",
)
ChaosCrypt_ERR_KeyPasswordIncorrect_E003 = _define(
"ChaosCrypt_ERR_KeyPasswordIncorrect_E003", "KeyPasswordIncorrect", "E003",
"The supplied key file password does not unlock this key file.",
)
ChaosCrypt_ERR_KeyNotLoaded_E004 = _define(
"ChaosCrypt_ERR_KeyNotLoaded_E004", "KeyNotLoaded", "E004",
"An operation requiring key material was attempted before any key "
"was loaded.",
)
ChaosCrypt_ERR_KeyFileExists_E005 = _define(
"ChaosCrypt_ERR_KeyFileExists_E005", "KeyFileExists", "E005",
"The target key file already exists and overwriting was not permitted.",
)
ChaosCrypt_ERR_EmptyPassword_E006 = _define(
"ChaosCrypt_ERR_EmptyPassword_E006", "EmptyPassword", "E006",
"A password was required but none was supplied.",
)
ChaosCrypt_ERR_PasswordMismatch_E007 = _define(
"ChaosCrypt_ERR_PasswordMismatch_E007", "PasswordMismatch", "E007",
"The two password entries did not match.",
)
ChaosCrypt_ERR_EmptyPlaintext_E008 = _define(
"ChaosCrypt_ERR_EmptyPlaintext_E008", "EmptyPlaintext", "E008",
"The plaintext to encrypt was empty.",
)
ChaosCrypt_ERR_EmptyCiphertext_E009 = _define(
"ChaosCrypt_ERR_EmptyCiphertext_E009", "EmptyCiphertext", "E009",
"The ciphertext to decrypt was empty.",
)
ChaosCrypt_ERR_MalformedCiphertext_E010 = _define(
"ChaosCrypt_ERR_MalformedCiphertext_E010", "MalformedCiphertext", "E010",
"The ciphertext is not valid hexadecimal or has an odd length.",
)
ChaosCrypt_ERR_DecryptionFailed_E011 = _define(
"ChaosCrypt_ERR_DecryptionFailed_E011", "DecryptionFailed", "E011",
"Decryption did not produce valid data: the password is wrong, the key "
"file does not match, or the ciphertext was altered.",
)
ChaosCrypt_ERR_EncodingFailed_E012 = _define(
"ChaosCrypt_ERR_EncodingFailed_E012", "EncodingFailed", "E012",
"A Base64 or UTF-8 encode/decode step failed.",
)
ChaosCrypt_ERR_InvalidArgument_E013 = _define(
"ChaosCrypt_ERR_InvalidArgument_E013", "InvalidArgument", "E013",
"An argument had an invalid type or value.",
)
ChaosCrypt_ERR_FileReadFailed_E014 = _define(
"ChaosCrypt_ERR_FileReadFailed_E014", "FileReadFailed", "E014",
"Reading a file failed with an I/O error.",
)
ChaosCrypt_ERR_FileWriteFailed_E015 = _define(
"ChaosCrypt_ERR_FileWriteFailed_E015", "FileWriteFailed", "E015",
"Writing a file failed with an I/O error.",
)
ChaosCrypt_ERR_UnsupportedKeyVersion_E016 = _define(
"ChaosCrypt_ERR_UnsupportedKeyVersion_E016", "UnsupportedKeyVersion", "E016",
"The key file declares a format version this build cannot read.",
)
ChaosCrypt_ERR_MissingMagicHeader_E017 = _define(
"ChaosCrypt_ERR_MissingMagicHeader_E017", "MissingMagicHeader", "E017",
"The input does not begin with the ChaosCrypt magic header. Every key file "
"and ciphertext produced by this system carries a self-describing header; "
"input without one is rejected outright.",
)
ChaosCrypt_ERR_MalformedHeader_E018 = _define(
"ChaosCrypt_ERR_MalformedHeader_E018", "MalformedHeader", "E018",
"The ChaosCrypt header is present but could not be parsed: a marker is "
"missing, the JSON is invalid, or a required field is absent.",
)