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
14 KiB
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.