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
This commit is contained in:
+463
@@ -0,0 +1,463 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user