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

464 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.