Files
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

688 lines
24 KiB
Python

"""
ChaosCrypt command line interface.
Invocation contract:
* ``chaoscrypt`` with no arguments launches the interactive TUI;
* ``chaoscrypt <command> ...`` runs a scriptable CLI command.
Every command supports ``--json`` for machine-readable output.
Exit codes:
0 success
1 runtime error (a ChaosCrypt error was raised)
2 usage error (argument parsing failed)
"""
from __future__ import annotations
import argparse
import json
import os
import sys
from typing import List, Optional
from . import (DEFAULT_KEY_FILE, __version__, MODES, DEFAULT_MODE,
ENCODINGS, DEFAULT_ENCODING, MIDS, DEFAULT_MID)
from .errors import ChaosCryptError, ChaosCrypt_ERR_InvalidArgument_E013
__all__ = ["build_parser", "main", "cli_main"]
PROG = "chaoscrypt"
EXIT_OK = 0
EXIT_ERROR = 1
EXIT_USAGE = 2
# ---------------------------------------------------------------------------
# Password resolution
# ---------------------------------------------------------------------------
def _resolve_password(
inline: Optional[str],
env: Optional[str],
file_path: Optional[str],
what: str = "password",
) -> Optional[str]:
"""Resolve a password from the command line.
Precedence is inline value, then environment variable, then file. Files
are read from their last non-empty line, so ``echo secret > .pwd`` works.
Raises:
ChaosCrypt_ERR_InvalidArgument_E013: the source was unreadable.
"""
if inline is not None:
return inline
if env:
val = os.environ.get(env)
if val is None:
raise ChaosCrypt_ERR_InvalidArgument_E013(
detail=f"EnvVarNotSet:{env}", code="E013"
)
return val
if file_path:
try:
with open(file_path, "r", encoding="utf-8") as f:
content = f.read()
except OSError as exc:
raise ChaosCrypt_ERR_InvalidArgument_E013(
detail=f"PasswordFileUnreadable:{exc}", code="E013"
)
lines = [ln.strip() for ln in content.splitlines() if ln.strip()]
if not lines:
raise ChaosCrypt_ERR_InvalidArgument_E013(
detail=f"PasswordFileEmpty:{file_path}", code="E013"
)
return lines[-1]
return None
def _add_global_flags(parser: argparse.ArgumentParser) -> None:
"""Re-register the global output flags on a subcommand.
``--json`` and ``--quiet`` are also accepted before the subcommand. Adding
them here as well lets users write either form, which is what most people
reach for first::
chaoscrypt --json info -k my.key -P keypwd
chaoscrypt info -k my.key -P keypwd --json
The values are merged in :func:`main` by taking whichever was set.
"""
parser.add_argument(
"-j", "--json", action="store_true", default=False,
dest="json_local",
help="emit machine-readable JSON on stdout",
)
parser.add_argument(
"-q", "--quiet", action="store_true", default=False,
dest="quiet_local",
help="suppress non-essential human-readable output",
)
parser.add_argument(
"--mode", choices=MODES, default=None, dest="mode_local", metavar="MODE",
help="performance mode: reference / fast / turbo / raw",
)
parser.add_argument(
"--encoding", choices=ENCODINGS, default=None, dest="encoding_local",
metavar="ENC", help="output encoding for turbo/raw: hex / base64",
)
parser.add_argument(
"--mid", choices=MIDS, default=None, dest="mid_local", metavar="MID",
help="intermediate representation for turbo/raw: bt / hex",
)
def _add_password_opts(
parser: argparse.ArgumentParser,
prefix: str,
label: str,
*,
dest_prefix: str = "",
long_prefix: str = "pwd",
) -> None:
"""Attach a standard password option group to a subcommand.
Args:
parser: Subcommand parser to extend.
prefix: Short option such as ``-p`` or ``-P``.
label: Human-readable label, e.g. ``"encryption password"``.
dest_prefix: Attribute prefix so two password groups can coexist.
long_prefix: Long option stem, e.g. ``pwd`` or ``key-pwd``.
"""
group = parser.add_argument_group(f"{label} options")
group.add_argument(
prefix,
f"--{long_prefix}",
dest=f"{dest_prefix}password",
metavar="PWD",
help=f"{label} on the command line "
f"(not recommended: visible in shell history)",
)
group.add_argument(
f"--{long_prefix}-env",
dest=f"{dest_prefix}password_env",
metavar="VAR",
help=f"read {label} from environment variable VAR",
)
group.add_argument(
f"--{long_prefix}-file",
dest=f"{dest_prefix}password_file",
metavar="PATH",
help=f"read {label} from the last non-empty line of PATH",
)
# ---------------------------------------------------------------------------
# Parser
# ---------------------------------------------------------------------------
def build_parser() -> argparse.ArgumentParser:
"""Build the top-level argument parser."""
parser = argparse.ArgumentParser(
prog=PROG,
description=(
"ChaosCrypt - a chaos-based obfuscation cipher.\n"
"Unaudited and non-standardised: intended for obfuscation, "
"personal use and study, not for production systems."
),
epilog=(
"examples:\n"
" chaoscrypt launch the interactive TUI\n"
" chaoscrypt keygen -k my.key --key-pwd-env KP\n"
" chaoscrypt encrypt \"hello\" -p secret -k my.key -P keypass\n"
" chaoscrypt decrypt \"1a2b...\" -p secret -k my.key -P keypass\n"
" chaoscrypt file encrypt photo.png -p secret -k my.key -P keypass\n"
" chaoscrypt info -k my.key -P keypass --json\n"
),
formatter_class=argparse.RawDescriptionHelpFormatter,
)
parser.add_argument(
"-V", "--version", action="version",
version=f"{PROG} {__version__} (MIT licence, unaudited, as-is)",
)
parser.add_argument(
"-j", "--json", action="store_true",
help="emit machine-readable JSON on stdout",
)
parser.add_argument(
"-q", "--quiet", action="store_true",
help="suppress non-essential human-readable output",
)
parser.add_argument(
"--mid", choices=MIDS, default=None, metavar="MID",
help=(
"intermediate representation for turbo/raw: 'bt' (bytes, default, "
"2.00x expansion) or 'hex' (hexadecimal text, ~4x). Ignored by "
"reference/fast."
),
)
parser.add_argument(
"--encoding", choices=ENCODINGS, default=None, metavar="ENC",
help=(
"output encoding for turbo/raw: 'hex' (2.00x expansion) or "
"'base64' (1.33x). Ignored by reference/fast, which always emit "
f"hex. Default: {DEFAULT_ENCODING}"
),
)
parser.add_argument(
"--mode", choices=MODES, default=None, metavar="MODE",
help=(
"performance mode. "
"'reference' is the original algorithm (slowest, baseline); "
"'fast' is bit-for-bit identical to it but uses C-level bulk "
"operations; 'turbo' derives the keystream with SHAKE256 and is "
"far faster, but its ciphertexts are not interchangeable with the "
f"other two. Default: {DEFAULT_MODE}"
),
)
sub = parser.add_subparsers(dest="command", metavar="<command>")
# ------------------------------------------------------------------ keygen
p_keygen = sub.add_parser(
"keygen", help="generate a new key file",
description="Generate a new ChaosCrypt key file.",
)
_add_global_flags(p_keygen)
p_keygen.add_argument(
"-k", "--key-file", default=DEFAULT_KEY_FILE, metavar="PATH",
help=f"output key file (default: {DEFAULT_KEY_FILE})",
)
p_keygen.add_argument(
"-f", "--force", action="store_true",
help="overwrite if the target already exists",
)
_add_password_opts(p_keygen, "-P", "key file password",
dest_prefix="key_", long_prefix="key-pwd")
# ----------------------------------------------------------------- encrypt
p_enc = sub.add_parser(
"encrypt", help="encrypt text",
description="Encrypt a string into a hexadecimal ciphertext.",
)
_add_global_flags(p_enc)
p_enc.add_argument("text", nargs="?", help="plaintext (use - for stdin)")
p_enc.add_argument(
"-i", "--in", dest="in_file", metavar="PATH",
help="read plaintext from a file instead of argv",
)
p_enc.add_argument(
"-o", "--out", dest="out_file", metavar="PATH",
help="write ciphertext to a file instead of stdout",
)
p_enc.add_argument(
"-k", "--key-file", default=DEFAULT_KEY_FILE, metavar="PATH",
help=f"key file (default: {DEFAULT_KEY_FILE})",
)
_add_password_opts(p_enc, "-p", "encryption password",
dest_prefix="", long_prefix="pwd")
_add_password_opts(p_enc, "-P", "key file password",
dest_prefix="key_", long_prefix="key-pwd")
# ----------------------------------------------------------------- decrypt
p_dec = sub.add_parser(
"decrypt", help="decrypt text",
description="Decrypt a hexadecimal ciphertext back into text.",
)
_add_global_flags(p_dec)
p_dec.add_argument("text", nargs="?", help="ciphertext (use - for stdin)")
p_dec.add_argument(
"-i", "--in", dest="in_file", metavar="PATH",
help="read ciphertext from a file instead of argv",
)
p_dec.add_argument(
"-o", "--out", dest="out_file", metavar="PATH",
help="write plaintext to a file instead of stdout",
)
p_dec.add_argument(
"-k", "--key-file", default=DEFAULT_KEY_FILE, metavar="PATH",
help=f"key file (default: {DEFAULT_KEY_FILE})",
)
_add_password_opts(p_dec, "-p", "encryption password",
dest_prefix="", long_prefix="pwd")
_add_password_opts(p_dec, "-P", "key file password",
dest_prefix="key_", long_prefix="key-pwd")
# -------------------------------------------------------------------- file
p_file = sub.add_parser(
"file", help="encrypt or decrypt whole files (binary-safe)",
description="Binary-safe file encryption and decryption.",
)
file_sub = p_file.add_subparsers(dest="file_command", metavar="<action>")
p_fe = file_sub.add_parser("encrypt", help="encrypt a file to .cc")
_add_global_flags(p_fe)
p_fe.add_argument("src", help="source file")
p_fe.add_argument(
"-o", "--out", dest="out_file", metavar="PATH",
help="output path (default: <src>.cc)",
)
p_fe.add_argument("-k", "--key-file", default=DEFAULT_KEY_FILE, metavar="PATH")
_add_password_opts(p_fe, "-p", "encryption password",
dest_prefix="", long_prefix="pwd")
_add_password_opts(p_fe, "-P", "key file password",
dest_prefix="key_", long_prefix="key-pwd")
p_fd = file_sub.add_parser("decrypt", help="decrypt a .cc file")
_add_global_flags(p_fd)
p_fd.add_argument("src", help="source .cc file")
p_fd.add_argument(
"-o", "--out", dest="out_file", metavar="PATH",
help="output path (default: strip the .cc suffix)",
)
p_fd.add_argument("-k", "--key-file", default=DEFAULT_KEY_FILE, metavar="PATH")
_add_password_opts(p_fd, "-p", "encryption password",
dest_prefix="", long_prefix="pwd")
_add_password_opts(p_fd, "-P", "key file password",
dest_prefix="key_", long_prefix="key-pwd")
# -------------------------------------------------------------------- info
p_info = sub.add_parser(
"info", help="show key file metadata",
description="Show metadata for a key file. Secret material is "
"redacted unless --show-maps is given.",
)
_add_global_flags(p_info)
p_info.add_argument(
"-k", "--key-file", default=DEFAULT_KEY_FILE, metavar="PATH",
help=f"key file (default: {DEFAULT_KEY_FILE})",
)
_add_password_opts(p_info, "-P", "key file password",
dest_prefix="key_", long_prefix="key-pwd")
p_info.add_argument(
"--show-maps", action="store_true",
help="also print the substitution tables (sensitive)",
)
# ------------------------------------------------------------------- chpwd
p_chpwd = sub.add_parser(
"chpwd", help="change a key file password",
description="Re-wrap an existing key file under a new password. "
"The key material itself is unchanged.",
)
_add_global_flags(p_chpwd)
p_chpwd.add_argument(
"-k", "--key-file", default=DEFAULT_KEY_FILE, metavar="PATH",
)
_add_password_opts(p_chpwd, "-P", "current key file password",
dest_prefix="key_", long_prefix="key-pwd")
p_chpwd.add_argument(
"--new-pwd", metavar="PWD", help="new key file password",
)
p_chpwd.add_argument(
"--new-pwd-env", metavar="VAR",
help="read the new key file password from environment variable VAR",
)
p_chpwd.add_argument(
"--new-pwd-file", metavar="PATH",
help="read the new key file password from PATH",
)
# --------------------------------------------------------------------- tui
sub.add_parser(
"tui", help="launch the interactive TUI",
description="Launch the interactive terminal UI, identical to "
"running chaoscrypt with no arguments.",
)
return parser
# ---------------------------------------------------------------------------
# Output helpers
# ---------------------------------------------------------------------------
def _emit(payload: dict, args: argparse.Namespace,
human_lines: Optional[List[str]] = None) -> None:
"""Print either JSON or human-readable lines."""
if getattr(args, "json", False):
print(json.dumps(payload, ensure_ascii=False, indent=2))
return
if not getattr(args, "quiet", False) and human_lines:
for line in human_lines:
print(line)
def _err_exit(exc: ChaosCryptError, args: argparse.Namespace) -> int:
"""Report a unified error and return the runtime-error exit code."""
if getattr(args, "json", False):
print(json.dumps(
{"ok": False, "error": str(exc), "code": exc.code},
ensure_ascii=False, indent=2,
))
else:
print(f"error: {exc}", file=sys.stderr)
return EXIT_ERROR
def _read_input(inline: Optional[str], in_file: Optional[str],
what: str = "input") -> str:
"""Read payload from argv, a file, or stdin."""
if in_file:
try:
with open(in_file, "r", encoding="utf-8") as f:
return f.read().strip()
except OSError as exc:
raise ChaosCrypt_ERR_InvalidArgument_E013(
detail=f"InputFileUnreadable:{exc}", code="E013"
)
if inline is not None and inline != "-":
return inline
# '-' or nothing at all: read stdin.
data = sys.stdin.read()
if not data:
raise ChaosCrypt_ERR_InvalidArgument_E013(
detail=f"MissingInput:{what}", code="E013"
)
return data.strip()
# ---------------------------------------------------------------------------
# Command implementations
# ---------------------------------------------------------------------------
def _cmd_keygen(args: argparse.Namespace) -> int:
from . import ChaosCrypt
from .errors import ChaosCrypt_ERR_EmptyPassword_E006
pwd = _resolve_password(
args.key_password, args.key_password_env, args.key_password_file,
"key file password",
)
if pwd is None:
return _err_exit(
ChaosCrypt_ERR_EmptyPassword_E006(
detail="NoKeyFilePassword", code="E006"
),
args,
)
cc = ChaosCrypt(mode=args.mode, encoding=args.encoding, mid=args.mid)
path = cc.create_key(pwd, args.key_file, overwrite=args.force)
_emit(
{"ok": True, "key_file": os.path.abspath(path)},
args,
[f"Key file created: {os.path.abspath(path)}"],
)
return EXIT_OK
def _cmd_text(args: argparse.Namespace, mode: str) -> int:
from . import ChaosCrypt
from .errors import ChaosCrypt_ERR_EmptyPassword_E006, \
ChaosCrypt_ERR_FileWriteFailed_E015
pwd = _resolve_password(
args.password, args.password_env, args.password_file, "encryption password"
)
key_pwd = _resolve_password(
args.key_password, args.key_password_env, args.key_password_file,
"key file password",
)
if pwd is None or key_pwd is None:
return _err_exit(
ChaosCrypt_ERR_EmptyPassword_E006(
detail="MissingPassword", code="E006"
),
args,
)
text = _read_input(
args.text, args.in_file, "plaintext" if mode == "encrypt" else "ciphertext"
)
cc = ChaosCrypt(mode=args.mode, encoding=args.encoding, mid=args.mid)
cc.load(args.key_file, key_pwd)
if mode == "encrypt":
result = cc.encrypt(text, pwd)
payload = {"ok": True, "mode": "encrypt", "ciphertext": result}
else:
result = cc.decrypt(text, pwd)
payload = {"ok": True, "mode": "decrypt", "plaintext": result}
if args.out_file:
try:
with open(args.out_file, "w", encoding="utf-8") as f:
f.write(result)
except OSError as exc:
return _err_exit(
ChaosCrypt_ERR_FileWriteFailed_E015(
detail=f"OutputWriteFailed:{exc}", code="E015"
),
args,
)
payload["out_file"] = os.path.abspath(args.out_file)
if not args.json and not args.quiet:
print(f"Written to: {os.path.abspath(args.out_file)}")
return EXIT_OK
_emit(payload, args, [result])
return EXIT_OK
def _cmd_file(args: argparse.Namespace, mode: str) -> int:
from . import ChaosCrypt
from .errors import ChaosCrypt_ERR_EmptyPassword_E006
pwd = _resolve_password(
args.password, args.password_env, args.password_file, "encryption password"
)
key_pwd = _resolve_password(
args.key_password, args.key_password_env, args.key_password_file,
"key file password",
)
if pwd is None or key_pwd is None:
return _err_exit(
ChaosCrypt_ERR_EmptyPassword_E006(
detail="MissingPassword", code="E006"
),
args,
)
cc = ChaosCrypt(mode=args.mode, encoding=args.encoding, mid=args.mid)
cc.load(args.key_file, key_pwd)
if mode == "encrypt":
out = cc.encrypt_file(args.src, pwd, args.out_file)
else:
out = cc.decrypt_file(args.src, pwd, args.out_file)
_emit(
{
"ok": True,
"mode": f"file_{mode}",
"src": os.path.abspath(args.src),
"out_file": os.path.abspath(out),
},
args,
[f"{os.path.abspath(args.src)} -> {os.path.abspath(out)}"],
)
return EXIT_OK
def _cmd_info(args: argparse.Namespace) -> int:
from . import ChaosCrypt
from .errors import ChaosCrypt_ERR_EmptyPassword_E006
key_pwd = _resolve_password(
args.key_password, args.key_password_env, args.key_password_file,
"key file password",
)
if key_pwd is None:
return _err_exit(
ChaosCrypt_ERR_EmptyPassword_E006(
detail="NoKeyFilePassword", code="E006"
),
args,
)
cc = ChaosCrypt(mode=args.mode, encoding=args.encoding, mid=args.mid)
cc.load(args.key_file, key_pwd)
info = cc.info()
if not args.show_maps:
for k in ("upper_mapping", "lower_mapping", "digit_mapping", "equal_mapping"):
info[k] = f"<hidden, {len(info[k])} chars>"
if args.json:
print(json.dumps({"ok": True, **info}, ensure_ascii=False, indent=2))
return EXIT_OK
print("=" * 62)
print("ChaosCrypt key information")
print("=" * 62)
for key, val in info.items():
print(f"{key:<20}: {val}")
print("=" * 62)
return EXIT_OK
def _cmd_chpwd(args: argparse.Namespace) -> int:
from . import ChaosCrypt
from .errors import ChaosCrypt_ERR_EmptyPassword_E006
old = _resolve_password(
args.key_password, args.key_password_env, args.key_password_file,
"current key file password",
)
new = _resolve_password(
args.new_pwd, args.new_pwd_env, args.new_pwd_file, "new key file password"
)
if old is None or new is None:
return _err_exit(
ChaosCrypt_ERR_EmptyPassword_E006(
detail="MissingPassword", code="E006"
),
args,
)
cc = ChaosCrypt(mode=args.mode, encoding=args.encoding, mid=args.mid)
path = cc.change_key_password(old, new, args.key_file)
_emit(
{"ok": True, "key_file": os.path.abspath(path)},
args,
[f"Key file password updated: {os.path.abspath(path)}"],
)
return EXIT_OK
# ---------------------------------------------------------------------------
# Entry point
# ---------------------------------------------------------------------------
def main(argv: Optional[List[str]] = None) -> int:
"""Run the CLI.
With no arguments this delegates to the interactive TUI; otherwise the
requested subcommand runs.
"""
raw = list(sys.argv[1:] if argv is None else argv)
if not raw:
from .tui import run_tui
return run_tui()
parser = build_parser()
args = parser.parse_args(raw)
# `--json` / `--quiet` are accepted both before and after the subcommand.
# The subparser writes to separate destinations so that an unset
# subcommand flag cannot clobber an explicitly set global one; the two are
# merged here.
args.json = bool(getattr(args, "json", False)
or getattr(args, "json_local", False))
args.quiet = bool(getattr(args, "quiet", False)
or getattr(args, "quiet_local", False))
args.mode = (getattr(args, "mode", None)
or getattr(args, "mode_local", None)
or DEFAULT_MODE)
args.encoding = (getattr(args, "encoding", None)
or getattr(args, "encoding_local", None)
or DEFAULT_ENCODING)
args.mid = (getattr(args, "mid", None)
or getattr(args, "mid_local", None)
or DEFAULT_MID)
if args.command is None or args.command == "tui":
from .tui import run_tui
return run_tui()
try:
if args.command == "keygen":
return _cmd_keygen(args)
if args.command == "encrypt":
return _cmd_text(args, "encrypt")
if args.command == "decrypt":
return _cmd_text(args, "decrypt")
if args.command == "info":
return _cmd_info(args)
if args.command == "chpwd":
return _cmd_chpwd(args)
if args.command == "file":
if args.file_command == "encrypt":
return _cmd_file(args, "encrypt")
if args.file_command == "decrypt":
return _cmd_file(args, "decrypt")
parser.parse_args(["file", "--help"])
return EXIT_USAGE
except ChaosCryptError as exc:
return _err_exit(exc, args)
except KeyboardInterrupt:
print("\nInterrupted.", file=sys.stderr)
return EXIT_ERROR
parser.print_help()
return EXIT_USAGE
def cli_main() -> None:
"""``console_scripts`` entry point."""
sys.exit(main())
if __name__ == "__main__": # pragma: no cover
cli_main()