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

1900 lines
77 KiB
Python

"""
ChaosCrypt algorithm core.
This module is the algorithm itself. It is a faithful, behaviour-preserving
port of the original single-file implementation: every substitution table,
bit operation, loop bound and character-level rule is reproduced exactly.
What changed relative to the original script is only the *plumbing*:
* ``print`` / ``input`` calls were removed, so the module is usable as a library;
* failure paths raise :class:`~chaoscrypt.errors.ChaosCryptError` instead of
returning sentinel strings such as ``"decryption failed"``.
As a result, ciphertexts and key files are fully interoperable in **both**
directions with the original implementation.
Security notice
---------------
ChaosCrypt has not been independently audited and is not a standardised
cryptographic construction. It is intended for obfuscation, personal use, and
study. See ``SECURITY.md`` for the full design and threat analysis.
"""
from __future__ import annotations
import base64
import hashlib
import json
import os
from datetime import datetime
from ._header import (
MIDS,
DEFAULT_MID,
MID_BYTES,
build_header,
build_legacy_header,
is_legacy,
FIELD_IS_OLD,
FIELD_OLD_IS_KEY,
read_header,
strip_header,
KIND_CIPHERTEXT,
KIND_KEY,
MID_BYTES,
MID_HEX,
OUT_HEX,
OUT_BASE,
HEADER_VERSION,
)
from .errors import (
ChaosCryptError,
ChaosCrypt_ERR_KeyNotLoaded_E004,
ChaosCrypt_ERR_KeyFileCorrupted_E002,
ChaosCrypt_ERR_KeyPasswordIncorrect_E003,
ChaosCrypt_ERR_DecryptionFailed_E011,
ChaosCrypt_ERR_EmptyPassword_E006,
ChaosCrypt_ERR_EmptyPlaintext_E008,
ChaosCrypt_ERR_EmptyCiphertext_E009,
ChaosCrypt_ERR_MalformedCiphertext_E010,
ChaosCrypt_ERR_MissingMagicHeader_E017,
ChaosCrypt_ERR_MalformedHeader_E018,
)
__all__ = ["ChaosCryptCore", "KEYFILE_VERSION"]
def __version_str__() -> str:
"""Library version, resolved lazily to avoid a circular import."""
try:
from . import __version__
return __version__
except Exception: # pragma: no cover
return "unknown"
#: Version of the on-disk key file format.
KEYFILE_VERSION = 1
#: Marker separating the payload from its metadata inside the intermediate form.
_SEP = "|"
# ---------------------------------------------------------------------------
# Performance modes
# ---------------------------------------------------------------------------
# REFERENCE runs the algorithm exactly as originally written. Slowest; the
# baseline every other mode is validated against, and the only mode
# whose ciphertexts match the pre-2.2 releases.
# FAST identical algorithm and identical ciphertext, but the per-character
# Python loops are replaced with equivalent C-level bulk operations.
# TURBO derives the keystream with SHAKE256 instead of the hand-rolled
# expansion. Much faster and built on a standardised primitive, but
# the ciphertexts are its own.
# RAW keeps the pipeline in bytes end to end, so nothing doubles the
# payload on the way, and takes the keystream straight from SHAKE256
# with no expansion loop at all. Fastest by a wide margin, and the
# weakest of the four: see SECURITY.md.
MODE_REFERENCE = "reference"
MODE_FAST = "fast"
MODE_TURBO = "turbo"
MODE_RAW = "raw"
MODES = (MODE_REFERENCE, MODE_FAST, MODE_TURBO, MODE_RAW)
DEFAULT_MODE = MODE_FAST
_PRINT_MIN = 32
_PRINT_MAX = 126
_PRINT_SPAN = 95
# 256-entry table folding any value outside the printable range into it with the
# algorithm's ``v % 95 + 32`` rule. C-level ``bytes.translate`` does the work.
_PRINTABLE_TABLE = bytes(
((v % _PRINT_SPAN + _PRINT_MIN) if (v < _PRINT_MIN or v > _PRINT_MAX) else v)
for v in range(256)
)
# Case-swap table covering A-Z and a-z. The flip stage only ever sees
# Base64-derived text, so only these 52 characters can occur. Latin-1 letters
# that Python's str.isalpha also accepts (0xB5, 0xDF, 0xFF) cannot appear, and
# their swapcase results fall outside the byte range anyway.
_SWAP_TABLE = bytearray(range(256))
for _i in range(26):
_SWAP_TABLE[ord("ABCDEFGHIJKLMNOPQRSTUVWXYZ"[_i])] = ord("abcdefghijklmnopqrstuvwxyz"[_i])
_SWAP_TABLE[ord("abcdefghijklmnopqrstuvwxyz"[_i])] = ord("ABCDEFGHIJKLMNOPQRSTUVWXYZ"[_i])
_SWAP_TABLE = bytes(_SWAP_TABLE)
# Domain tags so no two SHAKE uses can produce related streams.
_TURBO_DOMAIN = b"ChaosCrypt-turbo-keystream-v1"
_TURBO_OUTER_TAG = "\x1fouter"
_RAW_DOMAIN = b"ChaosCrypt-raw-keystream-v1"
# ---------------------------------------------------------------------------
# Keystream caching
# ---------------------------------------------------------------------------
# The base output of _mix_keys depends only on (password, short_key) — not on
# how much keystream is eventually needed — so it can be reused within a
# process. That removes a fixed ~50 us cost per operation, which dominates
# short messages.
#
# Cache strategies, selected with the `cache` argument:
#
# "hash" key the cache by SHA256(password) so the password itself never
# sits in the cache. Default.
# "plain" key by the password string directly. Marginally faster, but the
# password stays resident in memory for as long as the cache entry
# lives.
# "none" no caching at all; every operation recomputes from scratch.
# "force" no caching, and additionally re-derives on every call even if a
# cache were somehow populated. For the strictest requirements.
CACHE_HASH = "hash"
CACHE_PLAIN = "plain"
CACHE_NONE = "none"
CACHE_FORCE = "force"
CACHES = (CACHE_HASH, CACHE_PLAIN, CACHE_NONE, CACHE_FORCE)
DEFAULT_CACHE = CACHE_HASH
# Output encoding for the byte-pipeline modes (turbo, raw). ``reference`` and
# ``fast`` always emit hex, matching the original algorithm.
#
# "hex" two characters per byte (2.00x expansion)
# "base64" four characters per three bytes (1.33x expansion)
#
# base64 produces a third less output; hex keeps every mode visually
# consistent. The choice affects only the final encode, never the speed.
ENC_HEX = "hex"
ENC_BASE64 = "base64"
ENCODINGS = (ENC_HEX, ENC_BASE64)
DEFAULT_ENCODING = ENC_HEX
#: Maximum number of cached base keystreams per core instance. Each entry is
#: about 514 bytes, so the ceiling is roughly 100 KiB.
CACHE_MAX_ENTRIES = 200
# Translation tables for _expand_keystream, shared across instances and calls.
# Mode 1's table depends only on ``iteration % 95``; mode 2's on the raw
# iteration. Each is a one-off 256-entry build.
_EXPAND_ADD_TABLES = {}
_EXPAND_XOR_TABLES = {}
#: Number of leading SHA256 bytes used as a cache key.
_CACHE_KEY_BYTES = 16
class ChaosCryptCore:
"""The ChaosCrypt algorithm, free of any I/O or user interaction.
Responsibilities:
* generating the random system key material (substitution tables, long and
short keys, flip pattern);
* wrapping that material into a password-protected key file;
* encrypting and decrypting text and arbitrary binary data.
Every failure is reported as a :class:`~chaoscrypt.errors.ChaosCryptError`
subclass.
"""
def __init__(self, mode: str = DEFAULT_MODE,
cache: str = DEFAULT_CACHE,
encoding: str = DEFAULT_ENCODING,
mid: str = DEFAULT_MID) -> None:
"""Create a core instance.
Args:
mode: Performance mode: ``reference``, ``fast``, ``turbo`` or
``raw``. Only ``reference`` and ``fast`` produce ciphertexts
compatible with pre-2.2 releases; ``turbo`` and ``raw`` define
their own formats.
cache: Keystream cache strategy: ``hash`` (default, keyed by
SHA256 of the password), ``plain`` (keyed by the password),
``none`` (no cache) or ``force`` (no cache, always re-derive).
Caching changes only the cost, never the output.
encoding: Output encoding for ``turbo`` and ``raw``: ``hex``
(default, 2.00x expansion) or ``base64`` (1.33x expansion).
Ignored by ``reference`` and ``fast``, which always emit hex.
mid: Intermediate representation for ``turbo`` and ``raw``:
``bt`` (default, raw bytes between the XOR layers) or ``hex``
(hexadecimal text, as the original pipeline used). Ignored by
``reference`` and ``fast``.
"""
if mode not in MODES:
raise ValueError(
f"unknown mode {mode!r}; expected one of {', '.join(MODES)}"
)
if cache not in CACHES:
raise ValueError(
f"unknown cache {cache!r}; expected one of {', '.join(CACHES)}"
)
# Accept the header's vocabulary ("base") as well as the constructor's
# ("base64"). Carrying two names for one concept is a trap for callers
# who read a header and pass the value straight back in.
if encoding == OUT_BASE:
encoding = ENC_BASE64
if encoding not in ENCODINGS:
raise ValueError(
f"unknown encoding {encoding!r}; expected one of "
f"{', '.join(ENCODINGS)} (or 'base')"
)
if mid == "bytes":
mid = MID_BYTES
if mid not in MIDS:
raise ValueError(
f"unknown mid {mid!r}; expected one of {', '.join(MIDS)}"
)
self.mode = mode
self.cache = cache
self.encoding = encoding
# Intermediate representation for the byte-pipeline modes. reference and
# fast ignore it: their pipeline is inherently character-based and
# always reports "hex".
self.mid = mid
# Base-keystream cache, keyed per the selected strategy. Bounded by
# CACHE_MAX_ENTRIES with simple FIFO eviction.
self._base_cache = {}
self._base_order = []
# SHAKE keystreams for TURBO/RAW, keyed by (cache_key, length, layer).
# These depend on the message length, so they only help when the same
# password is reused at the same size.
self._ks_cache = {}
self._ks_order = []
self._short_ords = ()
# Character remapping used to keep the ciphertext inside Base64's
# alphabet while the '=' padding is handled out-of-band.
self.special_encrypt = {
'+': '.',
'/': "'",
'=': '',
}
self.special_decrypt = {
'.': '+',
"'": '/',
}
self.flip_pattern = None
self.keys_loaded = False
# Key material; populated by generate_keymaterial() or load_keys*().
self.upper_mapping = None
self.lower_mapping = None
self.digit_mapping = None
self.equal_mapping = None
self.long_key = None
self.short_key = None
self.digit_reverse = None
self.equal_reverse = None
self.upper_original = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
self.lower_original = "abcdefghijklmnopqrstuvwxyz"
self.encrypt_map = {}
self.decrypt_map = {}
# ======================================================================
# Random key material
# ======================================================================
def _generate_random_alphabet(self, lowercase: bool = False) -> str:
"""Return a uniformly random permutation of the A-Z or a-z alphabet."""
chars = list(
"abcdefghijklmnopqrstuvwxyz" if lowercase
else "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
)
n = len(chars)
for i in range(n - 1, 0, -1):
j = int.from_bytes(os.urandom(1), 'big') % (i + 1)
chars[i], chars[j] = chars[j], chars[i]
return ''.join(chars)
def _generate_random_digit_mapping(self) -> dict:
"""Map each digit 0-9 to a distinct alphanumeric character."""
digits = list("0123456789")
mapping_chars = list(
"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
)
n = len(mapping_chars)
for i in range(n - 1, 0, -1):
j = int.from_bytes(os.urandom(1), 'big') % (i + 1)
mapping_chars[i], mapping_chars[j] = (
mapping_chars[j], mapping_chars[i]
)
mapping = {}
for i, d in enumerate(digits):
mapping[d] = mapping_chars[i]
return mapping
def _generate_random_equal_mapping(self) -> dict:
"""Map the Base64 padding counts 0-3 to distinct characters."""
chars = list("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz")
n = len(chars)
for i in range(n - 1, 0, -1):
j = int.from_bytes(os.urandom(1), 'big') % (i + 1)
chars[i], chars[j] = chars[j], chars[i]
return {
'0': chars[0],
'1': chars[1],
'2': chars[2],
'3': chars[3],
}
def _generate_random_flip_pattern(self) -> list:
"""Return a random 10-bit case-flip pattern."""
pattern = []
for _ in range(10):
bit = int.from_bytes(os.urandom(1), 'big') % 2
pattern.append(bit)
return pattern
def _generate_long_key(self, length: int = 4096) -> str:
"""Return a random hex string of ``length`` characters."""
chars = "0123456789abcdef"
result = []
for _ in range(length):
idx = int.from_bytes(os.urandom(1), 'big') % 16
result.append(chars[idx])
return ''.join(result)
def _generate_short_key(self, length: int = 512) -> str:
"""Return a shorter random hex string used for key derivation."""
chars = "0123456789abcdef"
result = []
for _ in range(length):
idx = int.from_bytes(os.urandom(1), 'big') % 16
result.append(chars[idx])
return ''.join(result)
# ======================================================================
# Key file wrapping
# ======================================================================
def _obfuscate_keys(self, keys_data: dict) -> str:
"""Encode the key material into a Base64 payload.
This is a transport encoding for the key file, not a security
boundary; confidentiality of the key file comes from the caller's
password (see :meth:`_xor_encrypt_data`).
"""
json_str = json.dumps(keys_data)
b64 = base64.b64encode(json_str.encode()).decode()
reversed_b64 = b64[::-1]
shifted = ''.join([chr((ord(c) + 1) % 128) for c in reversed_b64])
return base64.b64encode(shifted.encode()).decode()
def _deobfuscate_keys(self, obfuscated_data: str) -> dict:
"""Reverse :meth:`_obfuscate_keys`."""
try:
shifted = base64.b64decode(obfuscated_data.encode()).decode()
reversed_b64 = ''.join([chr((ord(c) - 1) % 128) for c in shifted])
b64 = reversed_b64[::-1]
json_str = base64.b64decode(b64.encode()).decode()
return json.loads(json_str)
except Exception:
raise ChaosCrypt_ERR_KeyFileCorrupted_E002()
# ======================================================================
# Password-based key file encryption
# ======================================================================
def _xor_encrypt_data(self, data: str, password: str) -> str:
"""XOR ``data`` with the repeated password, returning hex."""
result = []
key_len = len(password)
for i, char in enumerate(data):
xor_result = ord(char) ^ ord(password[i % key_len])
result.append(f"{xor_result:02x}")
return ''.join(result)
def _xor_decrypt_data(self, hex_data: str, password: str) -> str | None:
"""Reverse :meth:`_xor_encrypt_data`; ``None`` if the input is not hex."""
try:
result = []
key_len = len(password)
for i in range(0, len(hex_data), 2):
if i + 1 < len(hex_data):
hex_byte = hex_data[i:i + 2]
xor_result = (
int(hex_byte, 16) ^ ord(password[(i // 2) % key_len])
)
result.append(chr(xor_result))
return ''.join(result)
except Exception:
return None
# ======================================================================
# Key generation / loading
# ======================================================================
def generate_keymaterial(self) -> dict:
"""Generate a complete set of random key material.
The instance is left in the *loaded* state and is immediately usable
for encryption and decryption.
Returns:
The key material as a JSON-serialisable dictionary.
"""
self.upper_mapping = self._generate_random_alphabet(lowercase=False)
self.lower_mapping = self._generate_random_alphabet(lowercase=True)
self.digit_mapping = self._generate_random_digit_mapping()
self.equal_mapping = self._generate_random_equal_mapping()
self.flip_pattern = self._generate_random_flip_pattern()
self.long_key = self._generate_long_key(4096)
self.short_key = self._generate_short_key(512)
self.digit_reverse = {v: k for k, v in self.digit_mapping.items()}
self.equal_reverse = {v: k for k, v in self.equal_mapping.items()}
keys_data = {
'upper_mapping': self.upper_mapping,
'lower_mapping': self.lower_mapping,
'digit_mapping': self.digit_mapping,
'equal_mapping': self.equal_mapping,
'flip_pattern': self.flip_pattern,
'long_key': self.long_key,
'short_key': self.short_key,
'generated_at': datetime.now().isoformat(),
}
self.keys_loaded = True
self._build_maps()
return keys_data
def serialize_keys(self, key_password: str, save_path: str) -> str:
"""Generate key material and write it to ``save_path``.
The on-disk format is identical to the original implementation.
Returns:
The path that was written.
"""
if not key_password:
raise ChaosCrypt_ERR_EmptyPassword_E006(
detail="EmptyKeyFilePassword", code="E006"
)
keys_data = self.generate_keymaterial()
obfuscated = self._obfuscate_keys(keys_data)
encrypted = self._xor_encrypt_data(obfuscated, key_password)
# Key files carry the same self-describing header as ciphertexts, with
# kind="key". A reader therefore never has to know which kind of file it
# has been handed.
document = self._emit(encrypted, KIND_KEY)
with open(save_path, 'w') as f:
f.write(document)
return save_path
def _build_maps(self) -> None:
"""Derive the forward and inverse character substitution maps."""
self.upper_original = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
self.lower_original = "abcdefghijklmnopqrstuvwxyz"
self.encrypt_map = {}
self.decrypt_map = {}
for i in range(26):
self.encrypt_map[self.upper_original[i]] = self.upper_mapping[i]
self.encrypt_map[self.lower_original[i]] = self.lower_mapping[i]
self.decrypt_map[self.upper_mapping[i]] = self.upper_original[i]
self.decrypt_map[self.lower_mapping[i]] = self.lower_original[i]
# Byte-level equivalents of the two maps, for the C-level paths.
enc = bytearray(range(256))
for k, v in self.encrypt_map.items():
enc[ord(k)] = ord(v)
self._enc_table = bytes(enc)
dec = bytearray(range(256))
for k, v in self.decrypt_map.items():
dec[ord(k)] = ord(v)
self._dec_table = bytes(dec)
# Cache the short key's code points as bytes so _mix_keys_uncached does
# not rebuild them through ord() on every call.
self._short_ords = tuple(ord(c) for c in self.short_key)
self._base_cache = {}
self._base_order = []
def load_keys_from_text(self, encrypted_data: str, key_password: str) -> None:
"""Load key material from the *contents* of a key file.
Raises:
ChaosCrypt_ERR_EmptyPassword_E006: no password supplied.
ChaosCrypt_ERR_KeyFileCorrupted_E002: not a plausible key file.
ChaosCrypt_ERR_KeyPasswordIncorrect_E003: password does not match.
"""
if not key_password:
raise ChaosCrypt_ERR_EmptyPassword_E006(
detail="EmptyKeyFilePassword", code="E006"
)
text = (encrypted_data or "").strip()
if not text:
raise ChaosCrypt_ERR_KeyFileCorrupted_E002(
detail="EmptyKeyFile", code="E002"
)
# Every key file this library writes carries the header. Validate it and
# confirm the artefact really is a key, not a ciphertext.
_cfg, raw = self._extract(text, KIND_KEY)
raw = raw.strip()
if not raw:
raise ChaosCrypt_ERR_KeyFileCorrupted_E002(
detail="EmptyKeyFileBody", code="E002"
)
# The body is hex text. Anything else is a malformed file rather than a
# wrong password, so the two cases are reported distinctly.
try:
int(raw[:2], 16)
bytes.fromhex(raw)
except (ValueError, TypeError):
raise ChaosCrypt_ERR_KeyFileCorrupted_E002(
detail="KeyFileNotHexadecimal", code="E002"
)
decrypted = self._xor_decrypt_data(raw, key_password)
if decrypted is None:
raise ChaosCrypt_ERR_DecryptionFailed_E011()
# A wrong password yields a payload that fails to decode; that is a
# credential problem, not a damaged file.
try:
keys_data = self._deobfuscate_keys(decrypted)
except ChaosCrypt_ERR_KeyFileCorrupted_E002:
raise ChaosCrypt_ERR_KeyPasswordIncorrect_E003()
try:
self.upper_mapping = keys_data['upper_mapping']
self.lower_mapping = keys_data['lower_mapping']
self.digit_mapping = keys_data['digit_mapping']
self.equal_mapping = keys_data['equal_mapping']
self.flip_pattern = keys_data['flip_pattern']
self.long_key = keys_data['long_key']
self.short_key = keys_data['short_key']
except (KeyError, TypeError):
raise ChaosCrypt_ERR_KeyFileCorrupted_E002()
# Structural sanity check: a wrong password can occasionally decode
# into well-formed JSON that is nonetheless nonsense.
ok = (
isinstance(self.upper_mapping, str) and len(self.upper_mapping) == 26
and isinstance(self.lower_mapping, str) and len(self.lower_mapping) == 26
and isinstance(self.long_key, str) and len(self.long_key) > 0
and isinstance(self.short_key, str) and len(self.short_key) > 0
and isinstance(self.flip_pattern, list) and len(self.flip_pattern) > 0
and sorted(self.upper_mapping) == sorted("ABCDEFGHIJKLMNOPQRSTUVWXYZ")
and sorted(self.lower_mapping) == sorted("abcdefghijklmnopqrstuvwxyz")
and isinstance(self.digit_mapping, dict) and len(self.digit_mapping) == 10
and isinstance(self.equal_mapping, dict) and len(self.equal_mapping) == 4
)
if not ok:
raise ChaosCrypt_ERR_KeyPasswordIncorrect_E003()
self.digit_reverse = {v: k for k, v in self.digit_mapping.items()}
self.equal_reverse = {v: k for k, v in self.equal_mapping.items()}
self._build_maps()
self.keys_loaded = True
def load_keys(self, key_file: str, key_password: str) -> None:
"""Read a key file from disk and load it."""
with open(key_file, 'r') as f:
encrypted_data = f.read()
self.load_keys_from_text(encrypted_data, key_password)
# ======================================================================
# Internal primitives
# ======================================================================
def _ensure_printable(self, text: str) -> str:
"""Fold any character into the printable ASCII range.
``|`` (0x7C) is preserved because it separates the payload from its
metadata. It already lies inside the printable range, so the general
rule leaves it alone; the translation table reproduces that.
Values above U+00FF cannot be expressed in a 256-entry byte table, so
such text falls back to the per-character rule.
"""
if not text:
return text
try:
return text.encode('latin-1').translate(_PRINTABLE_TABLE).decode('latin-1')
except UnicodeEncodeError:
out = []
for c in text:
v = ord(c)
if v == 124:
out.append('|')
elif v < _PRINT_MIN or v > _PRINT_MAX:
out.append(chr(v % _PRINT_SPAN + _PRINT_MIN))
else:
out.append(c)
return ''.join(out)
def _cache_key(self, user_password: str):
"""Return the cache key for ``user_password``, or ``None`` if disabled.
``hash`` strategy hashes the password so it does not stay resident;
``plain`` uses it verbatim; ``none`` and ``force`` disable the cache.
"""
if self.cache == CACHE_HASH:
return hashlib.sha256(user_password.encode('utf-8')).digest()[:_CACHE_KEY_BYTES]
if self.cache == CACHE_PLAIN:
return user_password
return None
def _shake_cached(self, domain: bytes, user_password: str, length: int,
layer: int = 0) -> bytes:
"""Return SHAKE256 keystream bytes, cached when caching is enabled.
The stream is bound to the password, the length and the layer index,
exactly as the uncached version is. Caching only removes the cost of
recomputing a stream that has already been derived for this
``(password, length, layer)`` triple.
``force`` and ``none`` bypass the cache entirely, so the derivation is
always performed afresh.
"""
if not self.keys_loaded:
raise ChaosCrypt_ERR_KeyNotLoaded_E004()
ck = self._cache_key(user_password)
if ck is None:
return self._shake_stream(domain, user_password, length, layer)
key = (ck, length, layer)
hit = self._ks_cache.get(key)
if hit is not None:
return hit
stream = self._shake_stream(domain, user_password, length, layer)
if len(self._ks_order) >= CACHE_MAX_ENTRIES:
oldest = self._ks_order.pop(0)
self._ks_cache.pop(oldest, None)
self._ks_cache[key] = stream
self._ks_order.append(key)
return stream
@staticmethod
def _shake_stream(domain: bytes, user_password: str, length: int,
layer: int = 0) -> bytes:
"""Compute SHAKE256 keystream bytes without touching any cache."""
h = hashlib.shake_256()
h.update(domain)
h.update(layer.to_bytes(2, 'big'))
h.update(len(user_password).to_bytes(4, 'big'))
h.update(user_password.encode('utf-8'))
return h
def _base_keystream(self, user_password: str) -> str:
"""Compute (or fetch) the length-independent base keystream.
``_mix_keys`` performs the same work regardless of how much keystream is
ultimately required: it interleaves the password with the short key,
applies position-dependent bit operations, permutes in groups of four
and folds the result into the printable range. Every one of those steps
depends only on ``(password, short_key)``.
Computing it once and reusing it removes a fixed per-call cost that
dominates short messages. The result is identical either way, so
ciphertexts are unaffected.
"""
key = self._cache_key(user_password)
if key is not None:
hit = self._base_cache.get(key)
if hit is not None:
return hit
base = self._mix_keys_uncached(user_password)
if key is not None:
if len(self._base_order) >= CACHE_MAX_ENTRIES:
oldest = self._base_order.pop(0)
self._base_cache.pop(oldest, None)
self._base_cache[key] = base
self._base_order.append(key)
return base
def _mix_keys(self, user_password: str, target_length: int) -> str:
"""Mix the password with the short key into a printable stream.
Note the contract, which matches the original exactly: the result is
**not** truncated to ``target_length``. The base material is returned
as-is (514 characters for the default 512-nibble short key), and the
rotating expansion is applied only when *more* than the base is
required. Callers that need an exact length truncate the result
themselves -- :meth:`_derive_final_key` does so.
The base is cached because it depends only on ``(password, short_key)``,
never on the requested length.
"""
base = self._base_keystream(user_password)
if len(base) >= target_length:
return base
return ChaosCryptCore._expand_keystream(base, target_length)
def _mix_keys_uncached(self, user_password: str) -> str:
"""Mix the password with the short key into a printable stream.
Byte-for-byte identical to the original per-element formulation, with
four changes that remove Python-level work:
* the short key's code points are cached as ``bytes`` instead of being
rebuilt through ``ord()`` on every call;
* the three position-dependent bit operations run over strided slices
instead of indexing one element at a time;
* the grouped swap runs over four strided slices at once rather than a
loop with tuple assignment;
* the printable fold is a single ``bytes.translate``.
The fold still happens after the swap: the XOR branch can leave values
above 255, and folding earlier would change which values the swap moves.
"""
if not self.keys_loaded:
raise ChaosCrypt_ERR_KeyNotLoaded_E004()
pw = [ord(c) for c in user_password]
sk = self._short_ords # tuple of ints, may exceed 255? No: hex only
lp, ls = len(pw), len(sk)
shorter = lp if lp < ls else ls
# The password may contain code points above 255, so the interleave
# cannot be done with byte slices when it does. Fall back to a plain
# list build in that case; both paths produce the same int sequence.
if lp and ls and shorter and (lp <= 0 or all(v <= 0xFF for v in pw[:shorter])):
mixed = bytearray(shorter * 2)
mixed[0::2] = bytes(pw[:shorter])
mixed[1::2] = bytes(sk[:shorter])
if lp > shorter:
mixed.extend(pw[shorter:])
elif ls > shorter:
mixed.extend(sk[shorter:])
elif lp and ls:
mixed = []
for i in range(shorter):
mixed.append(pw[i])
mixed.append(sk[i])
if lp > shorter:
mixed.extend(pw[shorter:])
elif ls > shorter:
mixed.extend(sk[shorter:])
mixed = bytearray(mixed) if all(v <= 0xFF for v in mixed) else mixed
else:
mixed = bytearray(pw + list(sk))
# Normalise to bytearray only when every value fits; otherwise keep the
# list and use the general path below.
byte_path = isinstance(mixed, bytearray)
if not byte_path and all(v <= 0xFF for v in mixed):
mixed = bytearray(mixed)
byte_path = True
if byte_path:
mixed[0::3] = bytes((v << 1) & 0xFF for v in mixed[0::3])
mixed[1::3] = bytes(v >> 1 for v in mixed[1::3])
mixed[2::3] = bytes(v ^ 0x5A for v in mixed[2::3])
n4 = (len(mixed) // 4) * 4
if n4:
blk = bytes(mixed[:n4])
tmp = bytearray(blk)
tmp[0::4] = blk[3::4]
tmp[3::4] = blk[0::4]
tmp[1::4] = blk[2::4]
tmp[2::4] = blk[1::4]
mixed[:n4] = tmp
mixed.reverse()
return bytes(mixed).translate(_PRINTABLE_TABLE).decode('latin-1')
# General path for passwords with code points above 255.
for i in range(0, len(mixed), 3):
mixed[i] = (mixed[i] << 1) & 0xFF
for i in range(1, len(mixed), 3):
mixed[i] = (mixed[i] >> 1) & 0xFF
for i in range(2, len(mixed), 3):
mixed[i] = mixed[i] ^ 0x5A
for i in range(0, len(mixed) - 3, 4):
mixed[i], mixed[i + 3] = mixed[i + 3], mixed[i]
mixed[i + 1], mixed[i + 2] = mixed[i + 2], mixed[i + 1]
mixed.reverse()
return ''.join(
chr(x % _PRINT_SPAN + _PRINT_MIN)
if (x < _PRINT_MIN or x > _PRINT_MAX) else chr(x)
for x in mixed
)
@staticmethod
def _expand_keystream(base_key: str, target_length: int) -> str:
"""Extend ``base_key`` to ``target_length`` with three rotating modes.
Three properties make this fast:
* everything stays in ``bytes`` — chunks accumulate in a list of byte
strings and are joined once, instead of ``str +=`` which reallocates
the whole accumulator on every round;
* each mode is a byte translation, so a round costs one
``bytes.translate`` rather than a per-character loop;
* the translation tables are shared and cached across calls. Mode 1
adds ``iteration``, which only matters modulo 95, so its cache
saturates at 95 entries. Mode 2 XORs with ``iteration``, which has no
short period — masking it would collide distinct tables and silently
change the stream — so its cache is keyed by the raw iteration.
Output is byte-for-byte identical to the original nested-loop
formulation, which the frozen reference vectors enforce.
"""
reversed_base = base_key[::-1]
try:
rev_bytes = reversed_base.encode('latin-1')
except UnicodeEncodeError:
return ChaosCryptCore._expand_keystream_slow(base_key, target_length)
blen = len(base_key)
parts = [base_key.encode('latin-1')]
produced = blen
iteration = 0
while produced < target_length:
mode = iteration % 3
if mode == 0:
parts.append(rev_bytes)
elif mode == 1:
key = iteration % _PRINT_SPAN
table = _EXPAND_ADD_TABLES.get(key)
if table is None:
table = bytes(
(v + iteration) % _PRINT_SPAN + _PRINT_MIN
for v in range(256)
)
_EXPAND_ADD_TABLES[key] = table
parts.append(rev_bytes.translate(table))
else:
table = _EXPAND_XOR_TABLES.get(iteration)
if table is None:
table = bytes(
(v ^ iteration) % _PRINT_SPAN + _PRINT_MIN
for v in range(256)
)
_EXPAND_XOR_TABLES[iteration] = table
parts.append(rev_bytes.translate(table))
produced += blen
iteration += 1
return b''.join(parts)[:target_length].decode('latin-1')
@staticmethod
def _expand_keystream_slow(base_key: str, target_length: int) -> str:
"""Straightforward formulation of :meth:`_expand_keystream`.
Serves as the reference the fast path is validated against, and as a
fallback for input the byte path cannot take.
"""
parts = [base_key]
produced = len(base_key)
iteration = 0
while produced < target_length:
chunk = base_key[::-1]
if iteration % 3 == 1:
chunk = ''.join(
chr((ord(c) + iteration) % _PRINT_SPAN + _PRINT_MIN)
for c in chunk
)
elif iteration % 3 == 2:
chunk = ''.join(
chr((ord(c) ^ iteration) % _PRINT_SPAN + _PRINT_MIN)
for c in chunk
)
parts.append(chunk)
produced += len(chunk)
iteration += 1
return ''.join(parts)[:target_length]
def _derive_final_key(self, user_password: str, text_length: int) -> str:
"""Derive a keystream of exactly ``text_length`` printable characters.
The hex round trip runs through ``bytes.hex`` and ``bytes.fromhex`` and
the fold uses the translation table, replacing the per-character loop
with its ``int(x, 16)`` conversion.
Hex-encoding and then reversing operates on hex *characters*, not
nibbles, so each byte's two nibbles swap order. That is intentional in
the original and is preserved here.
"""
mixed_key = self._mix_keys(user_password, text_length * 2)
# mixed_key is always printable ASCII, so latin-1 round-trips it.
hex_bytes = mixed_key.encode('latin-1').hex().encode('ascii')
# The reversal is over the whole hex string, so the first text_length
# output characters come from the LAST text_length hex bytes -- i.e.
# the first 2*text_length characters of the reversed string. Only that
# prefix is decoded and folded; the rest was never read. Measured ~1.6x
# faster on a 16 KiB payload, with identical output.
reversed_hex = hex_bytes[::-1][:text_length * 2]
folded = bytes.fromhex(reversed_hex.decode('ascii')).translate(
_PRINTABLE_TABLE
)
final_key_str = folded.decode('latin-1')
if len(final_key_str) < text_length:
final_key_str = self._expand_keystream(final_key_str, text_length)
return self._ensure_printable(final_key_str)
def _apply_flip(self, text: str) -> str:
"""Swap the case of letters at positions selected by the flip pattern.
The pattern has a short period, so the text is split into at most
``period`` strided slices, each translated in one C-level call, instead
of testing every character.
Only A-Z and a-z can reach here: this runs on Base64-derived text whose
letters were already substituted within the same 52-character set.
Python's ``str.isalpha`` would also accept Latin-1 letters such as
0xB5, 0xDF and 0xFF, whose ``swapcase`` results fall outside the byte
range; those cannot occur, and the byte table does not represent them.
"""
if not text or not self.flip_pattern:
return text
try:
buf = bytearray(text.encode('latin-1'))
except UnicodeEncodeError:
out = []
pattern = self.flip_pattern
for i, ch in enumerate(text):
if ch.isalpha() and pattern[i % len(pattern)] == 1:
out.append(ch.swapcase())
else:
out.append(ch)
return ''.join(out)
period = len(self.flip_pattern)
for k, bit in enumerate(self.flip_pattern):
if bit:
sl = slice(k, None, period)
buf[sl] = bytes(buf[sl]).translate(_SWAP_TABLE)
return bytes(buf).decode('latin-1')
def _xor_encrypt_with_final_key(self, text: str, user_password: str) -> str:
"""XOR with the password-derived keystream, returning hex.
The keystream is derived at exactly ``len(text)``, so the repeating step
collapses to a straight copy and the XOR is one big-integer operation.
"""
final_key = self._derive_final_key(user_password, len(text))
tb = text.encode('latin-1')
kb = self._repeat_to(final_key.encode('latin-1'), len(tb))
return self._xor_bytes_hex(tb, kb)
def _xor_decrypt_with_final_key(
self, hex_text: str, user_password: str
) -> str | None:
"""Reverse :meth:`_xor_encrypt_with_final_key`."""
try:
raw = bytes.fromhex(hex_text)
except ValueError:
return None
n = len(raw)
if n == 0:
return ''
final_key = self._derive_final_key(user_password, n)
kb = self._repeat_to(final_key.encode('latin-1'), n)
xored = int.from_bytes(raw, 'big') ^ int.from_bytes(kb, 'big')
return xored.to_bytes(n, 'big').translate(
_PRINTABLE_TABLE
).decode('latin-1')
def _substitute_letters(self, text: str, mapping: dict) -> str:
"""Apply a single-character substitution table.
Passing one of the internal byte tables makes this a single
``bytes.translate`` call; a plain dictionary takes the straightforward
path. Output is identical either way.
"""
if mapping is self._enc_table or mapping is self._dec_table:
if text:
try:
return text.encode('latin-1').translate(mapping).decode('latin-1')
except UnicodeEncodeError:
pass
return ''.join(mapping.get(char, char) for char in text)
def _encode_digit(self, num_str: str) -> str:
"""Encode a decimal string through the digit substitution table."""
return ''.join(self.digit_mapping.get(char, char) for char in num_str)
def _decode_digit(self, encoded_str: str) -> str:
"""Reverse :meth:`_encode_digit`."""
return ''.join(
self.digit_reverse.get(char, char) for char in encoded_str
)
def _get_dynamic_key(self, text_length: int) -> str:
"""Return the long key, repeated to cover ``text_length`` characters.
The repetition uses a single multiply-and-slice rather than
``key += long_key`` in a loop. The loop version is quadratic: each
concatenation reallocates the whole accumulator, so covering a
5.6 MB intermediate took 866 ms and dominated the 1 MiB timings.
Multiplication is implemented in C and is linear; the same work now
takes about 3 ms, and the output is identical.
"""
lk = self.long_key
ll = len(lk)
if ll >= text_length:
return lk[:text_length]
return (lk * (text_length // ll + 1))[:text_length]
@staticmethod
def _xor_bytes_hex(data: bytes, key: bytes) -> str:
"""XOR two equal-length byte strings and return lowercase hex.
One big-integer XOR performs the whole buffer at C speed, replacing the
per-byte loop and its ``%02x`` formatting. Output is identical.
"""
n = len(data)
xored = int.from_bytes(data, 'big') ^ int.from_bytes(key, 'big')
return xored.to_bytes(n, 'big').hex()
@staticmethod
def _repeat_to(key: bytes, n: int) -> bytes:
"""Repeat ``key`` until it is exactly ``n`` bytes long."""
kl = len(key)
if kl == n:
return key
if kl > n:
return key[:n]
return (key * (n // kl + 1))[:n]
def _xor_encrypt_with_key(self, text: str, key: str) -> str:
"""XOR with an explicit key, returning hex.
The repeated-key step uses slice arithmetic rather than indexing with a
modulus inside the loop.
"""
tb = text.encode('latin-1')
kb = self._repeat_to(key.encode('latin-1'), len(tb))
return self._xor_bytes_hex(tb, kb)
def _xor_decrypt_with_key(self, hex_text: str, key: str) -> str | None:
"""Reverse :meth:`_xor_encrypt_with_key`.
Hex decoding, the XOR and the printable fold are all C-level. Returns
``None`` on malformed input, matching the original's behaviour.
"""
try:
raw = bytes.fromhex(hex_text)
except ValueError:
return None
n = len(raw)
if n == 0:
return ''
kb = self._repeat_to(key.encode('latin-1'), n)
xored = int.from_bytes(raw, 'big') ^ int.from_bytes(kb, 'big')
return xored.to_bytes(n, 'big').translate(
_PRINTABLE_TABLE
).decode('latin-1')
# ======================================================================
# Self-describing header
# ======================================================================
def _algorithm_label(self) -> str:
"""A stable identifier for the cipher family."""
return "chaoscrypt"
def _kdf_label(self) -> str:
"""Which keystream derivation this mode uses."""
if self.mode in (MODE_TURBO, MODE_RAW):
return "shake256"
return "expand"
def _mid_label(self) -> str:
"""Intermediate representation actually used by this mode.
reference and fast are character-based throughout, so they always
report ``hex``. turbo and raw report whichever the caller selected.
"""
if self.mode in (MODE_TURBO, MODE_RAW):
return self.mid
return MID_HEX
def _out_label(self) -> str:
"""Output encoding actually used by this mode."""
if self.mode in (MODE_TURBO, MODE_RAW):
return OUT_BASE if self.encoding == ENC_BASE64 else OUT_HEX
return OUT_HEX
def _key_summary(self) -> str:
"""A short, non-secret digest of the key material.
Lets a caller confirm that a ciphertext and a key file belong together
without exposing anything usable. It is a SHA256 over the public shape
of the key, truncated to 16 hex characters.
"""
h = hashlib.sha256()
h.update(self.upper_mapping.encode('ascii'))
h.update(self.lower_mapping.encode('ascii'))
h.update(self.long_key.encode('ascii'))
h.update(self.short_key.encode('ascii'))
return h.hexdigest()[:16]
def header_config(self, kind: str = KIND_CIPHERTEXT) -> dict:
"""Build the complete configuration record for this core.
The record is deliberately exhaustive: it states everything a reader
needs in order to reproduce the decryption path, so no parameter ever
has to be guessed or remembered out of band.
Args:
kind: Whether this describes a ciphertext or a key file.
Returns:
A JSON-serialisable dictionary.
"""
return {
# --- identity -------------------------------------------------
"kind": kind,
"alg": self._algorithm_label(),
"v": HEADER_VERSION,
"lib": __version_str__(),
# --- how the payload was produced -----------------------------
"mode": self.mode,
"mid": self._mid_label(),
"out": self._out_label(),
"cache": self.cache,
# --- cipher construction --------------------------------------
"kdf": self._kdf_label(),
"subst": "bijective",
"flip": "conditional",
"order": "base64>subst>flip>reverse>xor>xor",
"xor_layers": 2 if self.mode in (MODE_REFERENCE, MODE_FAST,
MODE_TURBO) else 2,
"compact": self.mode in (MODE_TURBO, MODE_RAW),
# --- key material shape (no secrets) --------------------------
"keybits": len(self.long_key) * 4,
"keyshort": len(self.short_key) * 4,
"flipbits": len(self.flip_pattern),
"ksum": self._key_summary(),
# --- integrity -------------------------------------------------
"b64": True,
"utf8": True,
}
def _apply_header_config(self, cfg: dict,
strict: bool = True) -> None:
"""Adopt the settings recorded in a header.
The artefact's own record wins over the caller's configuration. If a
ciphertext says it was produced in ``turbo`` with ``base64`` output,
that is how it will be decrypted, whatever the caller passed in.
Args:
cfg: The parsed configuration record.
strict: When ``True`` (the default), an unknown or missing mode is
rejected rather than silently ignored.
Raises:
ChaosCrypt_ERR_MalformedHeader_E018: the record names a mode this
build does not implement.
"""
# A legacy record says only "I am old"; there is no mode to read. The
# legacy path applies the original algorithm, tried as `fast` with a
# fallback to `reference`.
if cfg.get(FIELD_IS_OLD):
self._apply_legacy_config(cfg)
return
mode = cfg.get("mode")
if mode not in MODES:
raise ChaosCrypt_ERR_MalformedHeader_E018(
detail=f"UnknownModeInHeader:{mode}", code="E018"
)
self.mode = mode
out = cfg.get("out")
mid = cfg.get("mid")
if mode in (MODE_TURBO, MODE_RAW):
if out not in (OUT_HEX, OUT_BASE):
raise ChaosCrypt_ERR_MalformedHeader_E018(
detail=f"BadOutInHeader:{out}", code="E018"
)
if mid not in MIDS:
raise ChaosCrypt_ERR_MalformedHeader_E018(
detail=f"BadMidInHeader:{mid}", code="E018"
)
self.encoding = ENC_BASE64 if out == OUT_BASE else ENC_HEX
# The artefact states its own intermediate representation; decoding
# with the other one must not be attempted.
self.mid = mid
# reference and fast always use hex internally and emit hex; the fields
# are descriptive there.
def _emit(self, payload: str, kind: str = KIND_CIPHERTEXT) -> str:
"""Prefix ``payload`` with a complete header."""
return build_header(self.header_config(kind)) + payload
def _extract(self, text: str, kind: str = KIND_CIPHERTEXT) -> "tuple":
"""Validate the header on ``text`` and return (config, payload).
Raises:
ChaosCrypt_ERR_MissingMagicHeader_E017: no header present.
ChaosCrypt_ERR_MalformedHeader_E018: header unusable, or it
describes a key file when a ciphertext was expected (or the
reverse).
"""
cfg = read_header(text)
# A legacy artefact says only "I am old"; every other field is ignored.
if cfg.get(FIELD_IS_OLD):
return cfg, strip_header(text)
if cfg.get("kind") != kind:
raise ChaosCrypt_ERR_MalformedHeader_E018(
detail=f"KindMismatch:expected={kind},got={cfg.get('kind')}",
code="E018",
)
return cfg, strip_header(text)
# ======================================================================
# Legacy compatibility
# ======================================================================
# ======================================================================
# Byte-pipeline helpers (turbo / raw)
# ======================================================================
# ======================================================================
# Legacy compatibility
# ======================================================================
# ======================================================================
# Byte-pipeline helpers (turbo / raw)
# ======================================================================
# ======================================================================
# Legacy compatibility
# ======================================================================
# ======================================================================
# Byte-pipeline helpers (turbo / raw)
# ======================================================================
def _apply_legacy_config(self, cfg: dict) -> None:
"""Select the decryption path for a legacy artefact.
When ``is_old`` is true every other field is ignored, including
``mode``: the artefact predates the header, so there is nothing
meaningful to read.
The legacy path is ``fast`` first, falling back to ``reference``. Both
implement the original algorithm, so either can read pre-header
material; the fallback costs a second attempt only if the first fails.
``old_is_key`` distinguishes a legacy key file from a legacy ciphertext.
"""
self.mode = MODE_FAST
def _legacy_attempt_order(self):
"""Modes to try for a legacy artefact, in order."""
return (MODE_FAST, MODE_REFERENCE)
# ======================================================================
# Legacy compatibility
# ======================================================================
def _is_headed(self, text: str) -> bool:
"""Whether ``text`` already carries a valid header."""
try:
read_header(text)
return True
except ChaosCryptError:
return False
def wrap_legacy(self, text: str, is_key: bool = False) -> str:
"""Give a pre-header artefact a minimal header.
The payload is untouched; only a header is prefixed. The result is a
well-formed artefact, so it can be passed to the ordinary decrypt path
without any special handling downstream.
If ``text`` already has a header it is returned unchanged.
Args:
text: The artefact, with or without a header.
is_key: Whether it is a legacy key file rather than a ciphertext.
Returns:
An artefact that carries a valid header.
"""
if self._is_headed(text):
return text
return build_legacy_header(is_key) + text
def decrypt_legacy(self, ciphertext: str, user_password: str,
is_key: bool = False) -> str:
"""Decrypt an artefact that may predate the header.
Tries the ordinary path first; if the input has no header, one is
synthesised and the ordinary path is tried again. Legacy support is
therefore a wrapper around the normal path rather than a second
implementation of it, and the underlying decrypt still demands a
well-formed header.
Args:
ciphertext: The artefact to decrypt.
user_password: The encryption password.
is_key: Set when the input is a legacy key file.
Returns:
The recovered plaintext.
Raises:
ChaosCrypt_ERR_MissingMagicHeader_E017: the input could not be
interpreted even after wrapping.
ChaosCrypt_ERR_DecryptionFailed_E011: decryption failed.
"""
text = ciphertext.strip()
if self._is_headed(text):
return self.decrypt_text(text, user_password)
# Wrap once, then try each legacy mode against it. The payload is not
# touched, so a failure here is a mode mismatch rather than damage.
wrapped = self.wrap_legacy(text, is_key=is_key)
last = None
for mode in self._legacy_attempt_order():
saved = self.mode
try:
self.mode = mode
return self.decrypt_text(wrapped, user_password)
except ChaosCryptError as exc:
last = exc
self.mode = saved
# Still nothing: the artefact may have been the other kind.
wrapped_alt = self.wrap_legacy(text, is_key=not is_key)
for mode in self._legacy_attempt_order():
saved = self.mode
try:
self.mode = mode
return self.decrypt_text(wrapped_alt, user_password)
except ChaosCryptError as exc:
last = exc
self.mode = saved
raise last if last is not None else ChaosCrypt_ERR_DecryptionFailed_E011()
def decrypt_legacy_auto(self, ciphertext: str, user_password: str) -> str:
"""Like :meth:`decrypt_legacy` but probes the artefact kind itself.
Tries it as a ciphertext first, then as a key file, and reports success
only if one of the two verifies.
"""
text = ciphertext.strip()
if self._is_headed(text):
return self.decrypt_text(text, user_password)
last = None
for is_key in (False, True):
wrapped = self.wrap_legacy(text, is_key=is_key)
for mode in self._legacy_attempt_order():
saved = self.mode
try:
self.mode = mode
return self.decrypt_text(wrapped, user_password)
except ChaosCryptError as exc:
last = exc
self.mode = saved
raise last if last is not None else ChaosCrypt_ERR_DecryptionFailed_E011()
def load_legacy_keys(self, text: str, key_password: str) -> None:
"""Load a key file that may predate the header.
The header requirement is unchanged: a legacy key file is wrapped in a
minimal header and then loaded through the ordinary path.
"""
self.load_keys_from_text(self.wrap_legacy(text, is_key=True),
key_password)
# ======================================================================
# Byte-pipeline helpers (turbo / raw)
# ======================================================================
def _bytes_stages(self, data: bytes, forward: bool) -> bytes:
"""Apply substitution, case flip and reversal to raw bytes.
``forward=False`` runs the inverse, which is how the decrypt path undoes
it. Used by the byte-pipeline modes.
"""
table = self._enc_table if forward else self._dec_table
period = len(self.flip_pattern)
if forward:
buf = bytearray(data.translate(table))
for k, bit in enumerate(self.flip_pattern):
if bit:
sl = slice(k, None, period)
buf[sl] = bytes(buf[sl]).translate(_SWAP_TABLE)
buf.reverse()
return bytes(buf)
buf = bytearray(data)
buf.reverse()
for k, bit in enumerate(self.flip_pattern):
if bit:
sl = slice(k, None, period)
buf[sl] = bytes(buf[sl]).translate(_SWAP_TABLE)
return bytes(buf).translate(table)
def _encode_output(self, data: bytes) -> str:
"""Encode final ciphertext bytes per the selected encoding."""
if self.encoding == ENC_BASE64:
return base64.b64encode(data).decode('ascii')
return data.hex()
def _decode_input(self, text: str) -> bytes:
"""Decode ciphertext text back to bytes per the selected encoding."""
if self.encoding == ENC_BASE64:
return base64.b64decode(text.encode('ascii'), validate=True)
return bytes.fromhex(text)
def _byte_pipeline_encrypt(self, data: bytes, user_password: str) -> str:
"""Encrypt bytes for TURBO.
``mid`` selects the intermediate representation:
``bt`` bytes are carried directly between the XOR layers, so only the
final encode expands the payload.
``hex`` each layer's output is hex-encoded before the next layer XORs
it, mirroring the original character pipeline and doubling the
payload at every step.
The two are symmetric and neither falls back to the other: an artefact
is decrypted with the ``mid`` recorded in its header.
"""
body = self._bytes_stages(data, forward=True)
if self.mid == MID_HEX:
# layer 1: hex the staged bytes, XOR against the inner keystream
h1 = body.hex().encode('ascii')
ks1 = self._turbo_keystream(user_password, len(h1))
x1 = self._xor_bytes(h1, ks1)
# layer 2: hex that result, XOR against the outer keystream
h2 = x1.hex().encode('ascii')
ks2 = self._turbo_keystream(
user_password + _TURBO_OUTER_TAG, len(h2)
)
return self._xor_bytes(h2, ks2).hex()
ks1 = self._turbo_keystream(user_password, len(body))
x1 = self._xor_bytes(body, ks1)
ks2 = self._turbo_keystream(
user_password + _TURBO_OUTER_TAG, len(x1)
)
return self._encode_output(self._xor_bytes(x1, ks2))
def _byte_pipeline_decrypt(self, text: str, user_password: str) -> bytes:
"""Undo :meth:`_byte_pipeline_encrypt`, mirroring it step for step."""
if self.mid == MID_HEX:
out = bytes.fromhex(text)
# undo layer 2: recovers the hex text h2
ks2 = self._turbo_keystream(
user_password + _TURBO_OUTER_TAG, len(out)
)
h2 = self._xor_bytes(out, ks2)
try:
x1 = bytes.fromhex(h2.decode('ascii'))
except Exception:
raise ChaosCrypt_ERR_DecryptionFailed_E011()
# undo layer 1: recovers the hex text h1
ks1 = self._turbo_keystream(user_password, len(x1))
h1 = self._xor_bytes(x1, ks1)
try:
body = bytes.fromhex(h1.decode('ascii'))
except Exception:
raise ChaosCrypt_ERR_DecryptionFailed_E011()
return self._bytes_stages(body, forward=False)
raw = self._decode_input(text)
ks2 = self._turbo_keystream(
user_password + _TURBO_OUTER_TAG, len(raw)
)
x1 = self._xor_bytes(raw, ks2)
ks1 = self._turbo_keystream(user_password, len(x1))
body = self._xor_bytes(x1, ks1)
return self._bytes_stages(body, forward=False)
def _raw_pipeline_encrypt(self, data: bytes, user_password: str) -> str:
"""Encrypt bytes for RAW: long-key layer, then SHAKE layer.
``mid`` selects the intermediate representation as for TURBO. The
long-key XOR is what distinguishes RAW from TURBO and is kept in both
variants.
"""
body = self._bytes_stages(data, forward=True)
if self.mid == MID_HEX:
h1 = body.hex().encode('ascii')
lk = self._repeat_to(self.long_key.encode('ascii'), len(h1))
x1 = self._xor_bytes(h1, lk)
h2 = x1.hex().encode('ascii')
ks = self._raw_keystream(user_password, len(h2))
return self._xor_bytes(h2, ks).hex()
lk = self._repeat_to(self.long_key.encode('ascii'), len(body))
x1 = self._xor_bytes(body, lk)
ks = self._raw_keystream(user_password, len(x1))
return self._encode_output(self._xor_bytes(x1, ks))
def _raw_pipeline_decrypt(self, text: str, user_password: str) -> bytes:
"""Undo :meth:`_raw_pipeline_encrypt`, mirroring it step for step."""
if self.mid == MID_HEX:
out = bytes.fromhex(text)
ks = self._raw_keystream(user_password, len(out))
h2 = self._xor_bytes(out, ks)
try:
x1 = bytes.fromhex(h2.decode('ascii'))
except Exception:
raise ChaosCrypt_ERR_DecryptionFailed_E011()
lk = self._repeat_to(self.long_key.encode('ascii'), len(x1))
h1 = self._xor_bytes(x1, lk)
try:
body = bytes.fromhex(h1.decode('ascii'))
except Exception:
raise ChaosCrypt_ERR_DecryptionFailed_E011()
return self._bytes_stages(body, forward=False)
raw = self._decode_input(text)
ks = self._raw_keystream(user_password, len(raw))
x1 = self._xor_bytes(raw, ks)
lk = self._repeat_to(self.long_key.encode('ascii'), len(x1))
body = self._xor_bytes(x1, lk)
return self._bytes_stages(body, forward=False)
# ======================================================================
# TURBO keystream and pipeline
# ======================================================================
def _turbo_keystream(self, user_password: str, length: int) -> bytes:
"""Derive ``length`` bytes of keystream with SHAKE256.
The seed binds the password, the short key, the long key and the
requested length, so a keystream recovered from one message is useless
for any other size. SHAKE256 is a standardised extensible-output
function, which makes this faster and easier to justify than a
hand-rolled expansion.
"""
if not self.keys_loaded:
raise ChaosCrypt_ERR_KeyNotLoaded_E004()
ck = self._cache_key(user_password)
if ck is not None:
key = (ck, length, 0, "turbo")
hit = self._ks_cache.get(key)
if hit is not None:
return hit
h = hashlib.shake_256()
h.update(_TURBO_DOMAIN)
h.update(len(user_password).to_bytes(4, 'big'))
h.update(user_password.encode('utf-8'))
h.update(len(self.short_key).to_bytes(4, 'big'))
h.update(self.short_key.encode('ascii'))
h.update(self.long_key.encode('ascii'))
h.update(length.to_bytes(8, 'big'))
stream = h.digest(length)
if ck is not None:
if len(self._ks_order) >= CACHE_MAX_ENTRIES:
oldest = self._ks_order.pop(0)
self._ks_cache.pop(oldest, None)
self._ks_cache[key] = stream
self._ks_order.append(key)
return stream
@staticmethod
def _xor_bytes(raw: bytes, key: bytes) -> bytes:
"""XOR two equal-length byte strings, returning bytes."""
n = len(raw)
if n == 0:
return b''
return (
int.from_bytes(raw, 'big') ^ int.from_bytes(key, 'big')
).to_bytes(n, 'big')
def _turbo_decrypt_outer(self, hex_text: str, user_password: str) -> str | None:
"""Undo the TURBO outer XOR layer."""
try:
raw = bytes.fromhex(hex_text)
except ValueError:
return None
n = len(raw)
if n == 0:
return ''
ks = self._turbo_keystream(user_password + _TURBO_OUTER_TAG, n)
return self._xor_bytes(raw, ks).translate(_PRINTABLE_TABLE).decode('latin-1')
def _turbo_decrypt_inner(
self, hex_text: str, user_password: str, key_length: int
) -> str | None:
"""Undo the TURBO inner XOR layer."""
try:
raw = bytes.fromhex(hex_text)
except ValueError:
return None
n = len(raw)
if n == 0:
return ''
ks = self._repeat_to(self._turbo_keystream(user_password, key_length), n)
return self._xor_bytes(raw, ks).translate(_PRINTABLE_TABLE).decode('latin-1')
# ======================================================================
# RAW keystream and pipeline
# ======================================================================
def _raw_keystream(self, user_password: str, length: int) -> bytes:
"""Derive ``length`` bytes of keystream with SHAKE256, with no expansion.
This is the only thing RAW changes relative to the original algorithm:
the original derived its keystream by mixing the password with the short
key and then *expanding* the result with a loop that ran once per 1024
bytes of output. SHAKE256 is an extensible-output function, so it
produces the same amount of keystream in a single call.
Every other stage is untouched: Base64, substitution, the case flip,
the reversal and the long-key XOR all behave as in the original.
The seed binds the password, the short key and the requested length, so
a keystream recovered from one message is useless for any other size,
and the password still contributes.
"""
if not self.keys_loaded:
raise ChaosCrypt_ERR_KeyNotLoaded_E004()
ck = self._cache_key(user_password)
if ck is not None:
key = (ck, length, 0, "raw")
hit = self._ks_cache.get(key)
if hit is not None:
return hit
h = hashlib.shake_256()
h.update(_RAW_DOMAIN)
h.update(len(user_password).to_bytes(4, 'big'))
h.update(user_password.encode('utf-8'))
h.update(len(self.short_key).to_bytes(4, 'big'))
h.update(self.short_key.encode('ascii'))
h.update(length.to_bytes(8, 'big'))
stream = h.digest(length)
if ck is not None:
if len(self._ks_order) >= CACHE_MAX_ENTRIES:
oldest = self._ks_order.pop(0)
self._ks_cache.pop(oldest, None)
self._ks_cache[key] = stream
self._ks_order.append(key)
return stream
def encrypt_text(self, plaintext: str, user_password: str) -> str:
"""Encrypt a string and return the ciphertext.
``reference`` and ``fast`` return hex, matching the original algorithm.
``turbo`` and ``raw`` return hex or base64 according to the ``encoding``
setting.
"""
if not self.keys_loaded:
raise ChaosCrypt_ERR_KeyNotLoaded_E004()
if not user_password:
raise ChaosCrypt_ERR_EmptyPassword_E006()
if plaintext is None or plaintext == "":
raise ChaosCrypt_ERR_EmptyPlaintext_E008()
if self.mode == MODE_TURBO:
body = self._byte_pipeline_encrypt(
plaintext.encode('utf-8'), user_password
)
return self._emit(body, KIND_CIPHERTEXT)
if self.mode == MODE_RAW:
body = self._raw_pipeline_encrypt(
plaintext.encode('utf-8'), user_password
)
return self._emit(body, KIND_CIPHERTEXT)
# Stage 1 - Base64 lifts arbitrary bytes into printable ASCII.
b64 = base64.b64encode(plaintext.encode('utf-8')).decode('utf-8')
equal_count = b64.count('=')
# Stage 2 - remap the characters Base64 may emit, dropping the padding.
processed = b64
for old, new in self.special_encrypt.items():
processed = processed.replace(old, new)
processed = processed.rstrip('=')
# Stage 3 - substitution, case flipping, reversal.
sub = self._substitute_letters(processed, self._enc_table)
reversed_text = self._apply_flip(sub)[::-1]
# Stage 4 - keep the padding count so decryption can restore it.
equal_char = self.equal_mapping[str(equal_count)]
with_equal = f"{reversed_text}{_SEP}{equal_char}"
key_length_encoded = self._encode_digit(str(len(with_equal)))
# Stage 5 - the two keystream layers.
dynamic_key = self._get_dynamic_key(len(with_equal))
encrypted_by_dynamic = self._xor_encrypt_with_key(with_equal, dynamic_key)
combined = f"{encrypted_by_dynamic}{_SEP}{key_length_encoded}"
body = self._xor_encrypt_with_final_key(combined, user_password)
return self._emit(body, KIND_CIPHERTEXT)
def decrypt_text(self, ciphertext: str, user_password: str) -> str:
"""Decrypt a ciphertext back into the original string."""
if not self.keys_loaded:
raise ChaosCrypt_ERR_KeyNotLoaded_E004()
if not user_password:
raise ChaosCrypt_ERR_EmptyPassword_E006()
if ciphertext is None or ciphertext == "":
raise ChaosCrypt_ERR_EmptyCiphertext_E009()
# No strip() here: the header parser tolerates surrounding whitespace,
# and copying a multi-megabyte string twice per call is measurable.
_cfg, stripped = self._extract(ciphertext, KIND_CIPHERTEXT)
self._apply_header_config(_cfg)
if self.mode in (MODE_TURBO, MODE_RAW):
# Validate the shape before doing any work, so a corrupted
# ciphertext cannot silently decrypt into garbage.
# Shape check only. The payload is decoded by the pipeline a
# moment later, so scanning it twice here would double the cost of
# validating a multi-megabyte artefact for no benefit: the decoder
# already raises on anything malformed.
if self.encoding == ENC_BASE64:
if len(stripped) % 4 != 0:
raise ChaosCrypt_ERR_MalformedCiphertext_E010(
detail="MalformedBase64Length", code="E010"
)
elif len(stripped) % 2 != 0:
raise ChaosCrypt_ERR_MalformedCiphertext_E010(
detail="OddLengthCiphertext", code="E010"
)
try:
if self.mode == MODE_TURBO:
body = self._byte_pipeline_decrypt(stripped, user_password)
else:
body = self._raw_pipeline_decrypt(stripped, user_password)
except ChaosCryptError:
raise
except (ValueError, UnicodeError):
# The payload is not the alphabet `out` promises. That is a
# format problem, so report it as such rather than as a
# decryption failure.
raise ChaosCrypt_ERR_MalformedCiphertext_E010(
detail="PayloadNotInDeclaredAlphabet", code="E010"
)
except Exception:
raise ChaosCrypt_ERR_DecryptionFailed_E011()
try:
return body.decode('utf-8')
except UnicodeError:
raise ChaosCrypt_ERR_DecryptionFailed_E011()
# A payload that is not well-formed hexadecimal is a format problem,
# not a wrong password, so it is reported as E010 rather than E011.
# Decoding once here costs what the pipeline would have spent anyway,
# and it lets the two cases be told apart.
if len(stripped) % 2 != 0:
raise ChaosCrypt_ERR_MalformedCiphertext_E010(
detail="OddLengthCiphertext", code="E010"
)
try:
bytes.fromhex(stripped)
except ValueError:
raise ChaosCrypt_ERR_MalformedCiphertext_E010(
detail="NonHexadecimalCiphertext", code="E010"
)
try:
combined = self._xor_decrypt_with_final_key(stripped, user_password)
if combined is None:
raise ChaosCrypt_ERR_DecryptionFailed_E011()
if _SEP in combined:
parts = combined.split(_SEP)
hex_data = parts[0]
key_length_encoded = parts[1] if len(parts) >= 2 else 'g'
else:
hex_data, key_length_encoded = combined, 'g'
try:
key_length = int(self._decode_digit(key_length_encoded))
except ValueError:
key_length = 16
xor_decrypted = self._xor_decrypt_with_key(
hex_data, self._get_dynamic_key(key_length)
)
if xor_decrypted is None:
raise ChaosCrypt_ERR_DecryptionFailed_E011()
if _SEP in xor_decrypted:
main_part, equal_char = xor_decrypted.split(_SEP)
equal_count = int(self.equal_reverse.get(equal_char, '0'))
else:
main_part, equal_count = xor_decrypted, 0
sub = self._substitute_letters(
self._apply_flip(main_part[::-1]), self._dec_table
)
for old, new in self.special_decrypt.items():
sub = sub.replace(old, new)
b64_with_equal = sub + '=' * equal_count
if len(b64_with_equal) % 4 != 0:
raise ChaosCrypt_ERR_MalformedCiphertext_E010(
detail="PayloadLengthNotMultipleOfFour", code="E010"
)
try:
raw = base64.b64decode(
b64_with_equal.encode('utf-8'), validate=True
)
except Exception:
raise ChaosCrypt_ERR_MalformedCiphertext_E010(
detail="PayloadNotValidBase64", code="E010"
)
return raw.decode('utf-8')
except ChaosCryptError:
raise
except Exception:
raise ChaosCrypt_ERR_DecryptionFailed_E011()
def encrypt_bytes(self, data: bytes, user_password: str) -> str:
"""Encrypt arbitrary binary data.
``reference`` and ``fast`` return hex; ``turbo`` and ``raw`` return hex
or base64 per the ``encoding`` setting.
"""
if data is None or len(data) == 0:
raise ChaosCrypt_ERR_EmptyPlaintext_E008()
if self.mode == MODE_TURBO:
body = self._byte_pipeline_encrypt(data, user_password)
return self._emit(body, KIND_CIPHERTEXT)
if self.mode == MODE_RAW:
body = self._raw_pipeline_encrypt(data, user_password)
return self._emit(body, KIND_CIPHERTEXT)
return self.encrypt_text(
base64.b64encode(data).decode('ascii'), user_password
)
def decrypt_bytes(self, ciphertext: str, user_password: str) -> bytes:
"""Decrypt back into the original binary data."""
if self.mode in (MODE_TURBO, MODE_RAW):
try:
_cfg, stripped = self._extract(
ciphertext.strip(), KIND_CIPHERTEXT
)
self._apply_header_config(_cfg)
if self.mode == MODE_TURBO:
return self._byte_pipeline_decrypt(stripped, user_password)
return self._raw_pipeline_decrypt(stripped, user_password)
except ChaosCryptError:
raise
except Exception:
raise ChaosCrypt_ERR_DecryptionFailed_E011()
text = self.decrypt_text(ciphertext, user_password)
try:
return base64.b64decode(text.encode('ascii'))
except Exception:
raise ChaosCrypt_ERR_DecryptionFailed_E011()