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
1900 lines
77 KiB
Python
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()
|