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
160 lines
6.2 KiB
Python
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.",
|
|
)
|