Files
ChaosCrypt/docs/API.md
T
dvs 2529edac1d v2.1.6: Restructure as a distributable library
Restructure ChaosCrypt from a single-file script into a complete,
installable Python package with three interfaces: a typed Python API, an
argument-driven CLI, and a bilingual interactive TUI.

The algorithm itself is unchanged. Ciphertexts and key files remain fully
interoperable with the original implementation in both directions, which is
enforced by dedicated tests rather than merely documented.

Added
- Library API: ChaosCrypt facade plus ChaosCryptCore for the raw algorithm
- Unified error hierarchy: 16 named types, all ChaosCryptError subclasses,
  rendering as ChaosCrypt_ERR_<Detail>_<Code>
- CLI: keygen, encrypt, decrypt, file, info, chpwd, tui, with --json output,
  stdin/stdout piping, and three password sources per secret
- Bilingual TUI: English default, runtime switch to Chinese, getpass password
  entry with a non-TTY fallback that keeps it scriptable
- Binary and file support: encrypt_bytes/decrypt_bytes and
  encrypt_file/decrypt_file
- Key management: change_key_password rewraps without altering key material;
  export_key_text/load_from_text move a key without touching disk
- Documentation: SECURITY.md with the full design and threat analysis, plus
  docs/ covering the API, CLI, architecture and build process
- Test suite: 92 tests across round-trips, binary safety, key management,
  error types, CLI, TUI, i18n and legacy interoperability
- Packaging: pyproject.toml, setup.py compatibility shim, MANIFEST.in,
  py.typed, examples, MIT licence

Fixed
- Conflicting --pwd option between the -p and -P groups prevented the CLI
  from starting at all
- Wrong key file password reported as file corruption (E002); structural
  validation now distinguishes it from a damaged file (E003)
- export_key_text produced key material without loading it into the instance
- Non-hexadecimal input was accepted as ciphertext and silently decrypted
  into garbage, making corruption indistinguishable from success; malformed
  input now raises E010 before any processing
- TUI failed under piped input because getpass requires a TTY
- TUI kept reading the default key file name after generating a new one

Changed
- Source tree reorganised: the package lives at chaoscrypt/, with tests,
  examples and legacy alongside it; documentation and build artefacts at the
  repository root
- Code comments unified in English; public docstrings document parameters,
  return values and raised exceptions
- English is now the default UI language
- ChaosCryptChat removed from the repository
- Attribution updated to Dvs (DvsXT); project URLs point to Gitea
2026-09-27 17:03:05 +08:00

14 KiB
Raw Blame History

API Reference

Complete reference for the chaoscrypt Python API.

from chaoscrypt import ChaosCrypt          # high-level facade
from chaoscrypt import ChaosCryptCore      # raw algorithm
from chaoscrypt import ChaosCryptError     # base error class

Package contents

Name Kind Description
ChaosCrypt class Key file management plus encryption helpers
ChaosCryptCore class The algorithm, with no file handling
ChaosCryptError exception Base class for every error raised
encrypt function One-shot encrypt using a key file
decrypt function One-shot decrypt using a key file
create_key function One-shot key file generation
DEFAULT_KEY_FILE constant "encryption.key"
KEYFILE_VERSION constant On-disk key file format version (1)
__version__ constant Library version string
__license__ constant "MIT"

class ChaosCrypt

The facade most callers should use. Wraps key file handling around ChaosCryptCore.

Constructor

ChaosCrypt(
    key_file: str | None = None,
    key_password: str | None = None,
    *,
    auto_load: bool = False,
    default_key_file: str = "encryption.key",
)
Parameter Type Default Description
key_file str | None None Path to a key file
key_password str | None None Password protecting that key file
auto_load bool False Load the key file during construction
default_key_file str "encryption.key" File name used when key_file is omitted

When auto_load=True and the file cannot be loaded, the corresponding exception is raised from the constructor.

cc = ChaosCrypt("my.key", "key-password", auto_load=True)

Properties

loaded -> bool

Whether usable key material is currently held in memory.

cc = ChaosCrypt()
assert cc.loaded is False
cc.create_key("pwd", "my.key")
assert cc.loaded is True

is_loaded() -> bool

Method form of the same check, for call sites that read better that way.

Key management

create_key(key_password, key_file=None, *, overwrite=False) -> str

Generate a fresh key file.

Parameter Type Default Description
key_password str required Password that will protect the file
key_file str | None None Destination; defaults to the configured name
overwrite bool False Replace an existing file rather than refusing

Returns the path written.

Raises ChaosCrypt_ERR_EmptyPassword_E006 for an empty password, or ChaosCrypt_ERR_KeyFileExists_E005 if the file exists and overwrite is false.

cc = ChaosCrypt()
cc.create_key("strong-password", "my.key")
cc.create_key("strong-password", "my.key", overwrite=True)  # replace

Aliases generate_keys and create_key_file are provided for readability.

load(key_file=None, key_password=None) -> ChaosCrypt

Load a key file from disk. Falls back to the instance attributes, then to the default file name. Returns self, so calls can be chained.

Raises ChaosCrypt_ERR_KeyFileNotFound_E001, ChaosCrypt_ERR_EmptyPassword_E006, ChaosCrypt_ERR_KeyPasswordIncorrect_E003, or ChaosCrypt_ERR_KeyFileCorrupted_E002.

cc = ChaosCrypt().load("my.key", "key-password")

load_from_text(key_text, key_password) -> ChaosCrypt

Load key material directly from a key file's contents, without touching disk. Useful when the key is stored in a password manager or retrieved from a vault.

text = vault.read("chaoscrypt-key")
cc = ChaosCrypt().load_from_text(text, "key-password")

export_key_text(key_password) -> str

Generate key material and return it as text, writing nothing to disk. The instance becomes loaded and immediately usable.

cc = ChaosCrypt()
text = cc.export_key_text("key-password")
vault.write("chaoscrypt-key", text)
token = cc.encrypt("data", "encryption-password")   # usable right away

change_key_password(old_password, new_password, key_file=None) -> str

Re-wrap an existing key file under a new password. The key material is unchanged, so previously encrypted data remains readable.

Raises ChaosCrypt_ERR_EmptyPassword_E006 if the new password is empty, or ChaosCrypt_ERR_KeyFileNotFound_E001 / ChaosCrypt_ERR_KeyPasswordIncorrect_E003 if the old password does not unlock the file.

cc.change_key_password("old-password", "new-password", "my.key")

info() -> dict

Return a summary of the loaded key material.

{
    "key_file": "my.key",
    "version": 1,
    "upper_mapping": "QWERTYUIOPASDFGHJKLZXCVBNM",
    "lower_mapping": "qwertyuiopasdfghjklzxcvbnm",
    "digit_mapping": {...},
    "equal_mapping": {...},
    "flip_pattern": [1, 0, 1, 0, 0, 1, 0, 0, 1, 0],
    "long_key_length": 4096,
    "short_key_length": 512,
    "loaded": True,
}

The substitution tables describe the structure of your key file. Treat the result as sensitive.

Raises ChaosCrypt_ERR_KeyNotLoaded_E004 if nothing is loaded.

Encryption

encrypt(plaintext, password) -> str

Encrypt a string, returning a hexadecimal ciphertext.

token = cc.encrypt("hello world", "encryption-password")

Raises ChaosCrypt_ERR_KeyNotLoaded_E004, ChaosCrypt_ERR_EmptyPassword_E006, or ChaosCrypt_ERR_EmptyPlaintext_E008.

decrypt(ciphertext, password) -> str

Decrypt a hexadecimal ciphertext back into a string.

plain = cc.decrypt(token, "encryption-password")

Raises ChaosCrypt_ERR_MalformedCiphertext_E010 if the input is not valid hexadecimal, or ChaosCrypt_ERR_DecryptionFailed_E011 if the password is wrong, the key file does not match, or the ciphertext was altered.

encrypt_bytes(data, password) -> str

Encrypt arbitrary binary data. Returns a hexadecimal ciphertext.

raw = open("archive.zip", "rb").read()
token = cc.encrypt_bytes(raw, "encryption-password")

decrypt_bytes(ciphertext, password) -> bytes

Decrypt back into the original binary data.

restored = cc.decrypt_bytes(token, "encryption-password")
open("archive.restored.zip", "wb").write(restored)

File helpers

encrypt_file(src, password, dst=None) -> str

Encrypt a file on disk, writing UTF-8 hexadecimal ciphertext. When dst is omitted, the output path is src + ".cc". Returns the output path.

Raises ChaosCrypt_ERR_FileReadFailed_E014 or ChaosCrypt_ERR_FileWriteFailed_E015.

decrypt_file(src, password, dst=None) -> str

Decrypt a .cc ciphertext file, restoring the original bytes. When dst is omitted, a trailing .cc is stripped, or .out is appended. Returns the output path.

cc.encrypt_file("report.pdf", "encryption-password")
cc.decrypt_file("report.pdf.cc", "encryption-password")

class ChaosCryptCore

The algorithm itself, with no file handling and no user interaction. Use it when you manage key material yourself — for example by loading it from a database or a secrets service.

from chaoscrypt import ChaosCryptCore

core = ChaosCryptCore()
core.generate_keymaterial()                    # random key material
token = core.encrypt_text("hello", "password")
assert core.decrypt_text(token, "password") == "hello"

Key material methods

Method Description
generate_keymaterial() -> dict Generate a complete random key set; leaves the instance loaded
serialize_keys(key_password, save_path) -> str Generate and write a key file
load_keys(key_file, key_password) -> None Load a key file from disk
load_keys_from_text(text, key_password) -> None Load from key file contents

Encryption methods

Method Description
encrypt_text(plaintext, password) -> str Encrypt a string to hexadecimal
decrypt_text(ciphertext, password) -> str Decrypt to a string
encrypt_bytes(data, password) -> str Encrypt binary data
decrypt_bytes(ciphertext, password) -> bytes Decrypt to binary data

Attributes

Set by generate_keymaterial() or one of the load_keys* methods:

Attribute Type Description
keys_loaded bool Whether key material is present
upper_mapping str Bijection over A–Z, 26 characters
lower_mapping str Bijection over a–z, 26 characters
digit_mapping dict Digits 0–9 to distinct alphanumerics
equal_mapping dict Padding counts 0–3 to distinct characters
flip_pattern list[int] Ten bits controlling case flipping
long_key str 4096 hexadecimal nibbles
short_key str 512 hexadecimal nibbles

Attributes prefixed with an underscore are internal and not covered by the compatibility guarantee.


Error hierarchy

Every error is a subclass of ChaosCryptError, so a single except clause catches everything:

from chaoscrypt import ChaosCryptError

try:
    cc.decrypt(token, "password")
except ChaosCryptError as e:
    print(e.message)   # ChaosCrypt_ERR_DecryptionFailed_E011
    print(e.code)      # E011
    print(e.detail)    # DecryptionFailed
Code Class Raised when
E001 ChaosCrypt_ERR_KeyFileNotFound_E001 The key file does not exist
E002 ChaosCrypt_ERR_KeyFileCorrupted_E002 The key file cannot be parsed
E003 ChaosCrypt_ERR_KeyPasswordIncorrect_E003 Wrong key file password
E004 ChaosCrypt_ERR_KeyNotLoaded_E004 Operation needs a key, none loaded
E005 ChaosCrypt_ERR_KeyFileExists_E005 File exists and overwrite not permitted
E006 ChaosCrypt_ERR_EmptyPassword_E006 A required password was missing
E007 ChaosCrypt_ERR_PasswordMismatch_E007 Two password entries differed
E008 ChaosCrypt_ERR_EmptyPlaintext_E008 The plaintext was empty
E009 ChaosCrypt_ERR_EmptyCiphertext_E009 The ciphertext was empty
E010 ChaosCrypt_ERR_MalformedCiphertext_E010 Not valid hexadecimal, or odd length
E011 ChaosCrypt_ERR_DecryptionFailed_E011 Decryption produced invalid data
E012 ChaosCrypt_ERR_EncodingFailed_E012 Base64 or UTF-8 conversion failed
E013 ChaosCrypt_ERR_InvalidArgument_E013 An argument had an invalid value
E014 ChaosCrypt_ERR_FileReadFailed_E014 Reading a file failed
E015 ChaosCrypt_ERR_FileWriteFailed_E015 Writing a file failed
E016 ChaosCrypt_ERR_UnsupportedKeyVersion_E016 Key file version not supported

Codes are stable and safe to branch on. The human-readable portion of the message may be reworded between minor releases.

Custom details

Each error accepts an optional detail and code, which is useful for adding context such as a file path:

from chaoscrypt.errors import ChaosCrypt_ERR_KeyFileNotFound_E001

raise ChaosCrypt_ERR_KeyFileNotFound_E001(
    detail="KeyFileNotFound:/etc/keys/prod.key", code="E001"
)

Module-level functions

Convenience wrappers for scripts that perform a single operation.

encrypt(plaintext, password, key_file="encryption.key", key_password=None) -> str

Load a key file and encrypt in one call. When key_password is omitted it falls back to password, which suits setups where one secret guards both layers.

import chaoscrypt

token = chaoscrypt.encrypt("data", "user-pwd", "my.key", "key-pwd")

decrypt(ciphertext, password, key_file="encryption.key", key_password=None) -> str

The inverse of the above.

plain = chaoscrypt.decrypt(token, "user-pwd", "my.key", "key-pwd")

create_key(key_password, key_file="encryption.key", *, overwrite=False) -> str

Generate a key file in one call. Returns the path written.

chaoscrypt.create_key("key-pwd", "my.key")

Complete example

"""Encrypt a config file, then restore it."""

from chaoscrypt import ChaosCrypt, ChaosCryptError

KEY_FILE = "secrets.key"
KEY_PASSWORD = "key-file-password"
DATA_PASSWORD = "encryption-password"


def main() -> None:
    cc = ChaosCrypt()

    # Reuse an existing key file, or create one on first run.
    try:
        cc.load(KEY_FILE, KEY_PASSWORD)
    except ChaosCryptError:
        cc.create_key(KEY_PASSWORD, KEY_FILE)

    # Text round trip.
    token = cc.encrypt("API_KEY=abc123", DATA_PASSWORD)
    print(f"Ciphertext: {token}")
    print(f"Restored:   {cc.decrypt(token, DATA_PASSWORD)}")

    # File round trip.
    cc.encrypt_file("config.json", DATA_PASSWORD)
    cc.decrypt_file("config.json.cc", DATA_PASSWORD, "config.restored.json")

    # A wrong password is reported clearly.
    try:
        cc.decrypt(token, "not-the-password")
    except ChaosCryptError as e:
        print(f"Rejected as expected: {e} (code {e.code})")


if __name__ == "__main__":
    main()

Thread safety

ChaosCrypt and ChaosCryptCore instances are not thread-safe. Key material is mutable state on the instance, and loading a key while an encryption is in progress is a data race.

Either use one instance per thread, or create the instance once and guard it with a lock:

import threading
from chaoscrypt import ChaosCrypt

cc = ChaosCrypt().load("my.key", "key-password")
lock = threading.Lock()


def encrypt_safely(text: str, password: str) -> str:
    with lock:
        return cc.encrypt(text, password)

The module-level functions create a fresh instance on each call, so they are safe to use concurrently without a lock — at the cost of reloading the key file each time.


Compatibility guarantee

Within a major version:

  • the public API described here will not change incompatibly;
  • error codes will not be renumbered;
  • the key file format will not change;
  • ciphertexts produced by any earlier release will continue to decrypt.

The underscore-prefixed members of ChaosCryptCore are internal and may change without notice.