# API Reference Complete reference for the `chaoscrypt` Python API. ```python 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 ```python 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. ```python cc = ChaosCrypt("my.key", "key-password", auto_load=True) ``` ### Properties #### `loaded -> bool` Whether usable key material is currently held in memory. ```python 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. ```python 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`. ```python 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. ```python 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. ```python 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. ```python cc.change_key_password("old-password", "new-password", "my.key") ``` #### `info() -> dict` Return a summary of the loaded key material. ```python { "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. ```python 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. ```python 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. ```python 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. ```python 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. ```python 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. ```python 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: ```python 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: ```python 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. ```python 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. ```python 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. ```python chaoscrypt.create_key("key-pwd", "my.key") ``` --- ## Complete example ```python """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: ```python 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.