v4.2.6: Self-describing format, byte pipeline, and a performance pass

Every key file and ciphertext now carries a header that states how it was
produced: magic, two fixed markers, and a complete JSON configuration record.
A reader takes its parameters from the artefact rather than from the caller.

This is an incompatible format change. Headerless input is rejected with E017;
pre-4.2.6 material is read through a compatibility API that wraps it in a
minimal header and then uses the ordinary path, so the strict path stays strict.

Added
- Self-describing header on all artefacts, with a normative specification in
  docs/FORMAT.md
- E017 MissingMagicHeader and E018 MalformedHeader
- Byte pipeline for turbo and raw: the XOR layers exchange raw bytes rather
  than hexadecimal text, cutting expansion from 5.33x to 2.00x and raising
  throughput about 4x. The old behaviour is available as mid="hex".
- Selectable output encoding for turbo and raw: hex (2.00x) or base64 (1.33x)
- Legacy compatibility API: wrap_legacy, decrypt_legacy, decrypt_legacy_auto,
  load_legacy_keys
- Frozen reference vectors covering every mode, encoding and intermediate
- docs/benchmark.md with measured throughput and the profiling behind it

Changed
- Default mode is fast: byte-for-byte compatible with the original algorithm,
  roughly 30x quicker
- Substitution, case flipping and the printable fold use bytes.translate over
  precomputed tables
- XOR layers use one big-integer operation instead of a per-byte loop
- Keystream derivation caches length-independent base material; expansion uses
  cached translation tables and list accumulation rather than str +=
- _get_dynamic_key repeats by multiplication. The loop version was quadratic:
  covering a 5.6 MB intermediate took 866 ms, now 3 ms, output unchanged.
- _derive_final_key decodes only the prefix the output consumes
- The decrypt path no longer copies or scans the whole artefact: a redundant
  strip(), a full-string int(payload, 16), and three whole-string slices in
  strip_header were removed. Decryption at 512 KiB went from 34 to 87 MB/s.
- Documentation rewritten for 4.2.6; all eleven markdown files are English

Fixed
1. Key derivation is no longer quadratic (_get_dynamic_key and
   _expand_keystream_slow shared the str += pattern)
2. Two hex-intermediate pipelines were asymmetric, so a turbo or raw artefact
   written with mid="hex" could not be read back
3. change_key_password and export_key_text wrote artefacts without a header
4. The constructor accepted encoding="base64" while the header records
   out="base"; both spellings are now accepted
5. A payload that is not valid hexadecimal reports E010 (MalformedCiphertext)
   rather than E011 (DecryptionFailed)
6. The TUI encoding menu referenced a missing translation

Security
- Format break from pre-4.2.6 artefacts, documented rather than accidental
- fast is not a weaker mode: the frozen vectors assert identical output
- The header adds no secrecy and is not authenticated; an application that must
  detect header tampering should MAC the whole artefact

Performance
- raw with the default bt intermediate: ~60 MB/s encryption, ~70 MB/s
  decryption, ciphertext 2.00x the payload
- Throughput holds steady from 64 KiB to 1 GiB
- The original implementation managed 0.08 MB/s
This commit is contained in:
dvs
2026-09-27 22:06:34 +08:00
parent 24a36d6fb4
commit dd49043171
25 changed files with 5348 additions and 852 deletions
+163 -75
View File
@@ -7,93 +7,182 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
---
## [2.1.6] — 2026-09-27
## [4.2.6] — 2026-09-27
Packaging and documentation release. The algorithm is unchanged; this version
restructures the project as a distributable library and brings the
documentation in line with it.
Self-describing artefacts, a byte pipeline worth using, and a large performance
pass. This release changes the on-disk format incompatibly and is the first
version intended to be deployed rather than experimented with.
### Added
- **Bilingual interactive TUI.** A menu-driven interface with English and
Chinese, switchable at runtime. Uses `getpass` for password entry on a
terminal and degrades to plain input when piped, so it remains scriptable.
- **Full command line interface.** Subcommands `keygen`, `encrypt`, `decrypt`,
`file`, `info`, `chpwd` and `tui`, with `--json` output, stdin/stdout
piping, and three ways to supply each password (inline, environment
variable, password file).
- **Unified error hierarchy.** Sixteen named error types, all subclasses of
`ChaosCryptError`, each rendering as `ChaosCrypt_ERR_<Detail>_<Code>`. Every
failure path in the library now raises rather than returning a sentinel.
- **Binary and file support.** `encrypt_bytes` / `decrypt_bytes` for arbitrary
binary data, and `encrypt_file` / `decrypt_file` for whole files.
- **Key management helpers.** `change_key_password` re-wraps a key file under
a new password without altering the key material. `export_key_text` and
`load_from_text` move a key without touching disk.
- **Comprehensive documentation.** `SECURITY.md` presents the design, key
space derivation, threat model and attack analysis in full. `docs/`
contains API, CLI and architecture references.
- **Test suite.** Round-trip integrity, binary safety, key management, error
types, CLI behaviour, TUI interaction, internationalisation, and
bidirectional interoperability with the original implementation.
- **Packaging.** `pyproject.toml`, `MANIFEST.in`, `.gitignore`, `py.typed`,
runnable examples, and MIT licensing.
- **Self-describing header on every artefact.** Each key file and ciphertext now
begins with a magic value, two fixed markers, and a complete JSON
configuration record that states how the payload was produced. A reader never
has to be told the mode, the encoding or the intermediate representation: it
reads them. See [docs/FORMAT.md](docs/FORMAT.md).
```
69CES
385aeff1f4179a744c8fb0c5ae4702d325f6230d059f4251135c2536409dee93
{"alg":"chaoscrypt","kind":"ciphertext","mode":"turbo","out":"hex",...}
2025ea4e4b4b93803f2ccadeaf318d1957ce42ff5409410f660348be96a4c0f2
<payload>
```
- **Two new error codes**, for the two ways a header can be wrong:
- `E017 MissingMagicHeader` — the input is not a CES artefact at all
- `E018 MalformedHeader` — a marker is missing, the JSON is unusable, a
required field is absent, or `kind` does not match
- **Byte pipeline for `turbo` and `raw`.** Between the XOR layers the payload is
now carried as raw bytes rather than hexadecimal text. This removes a
doubling of the payload at each layer: expansion drops from **5.33x to 2.00x**
and throughput rises by roughly **4x**. The old behaviour is still available
as `mid="hex"`.
- **Selectable output encoding** for `turbo` and `raw`: `hex` (2.00x) or
`base64` (1.33x).
- **Legacy compatibility API**, for artefacts written before the header existed:
- `wrap_legacy(text, is_key)` — synthesise a minimal header and return a
well-formed artefact
- `decrypt_legacy(text, password, is_key)` — read an artefact that may predate
the header
- `decrypt_legacy_auto(text, password)` — as above, probing whether the input
is a key file or a ciphertext
- `load_legacy_keys(text, key_password)` — load a pre-header key file
Legacy support is a *wrapper* around the ordinary path, never a lenient branch
inside it: the payload is given a header and then read normally, so the strict
path stays strict.
- **Frozen reference vectors** covering eleven cases across every mode,
encoding and intermediate representation, plus five error cases.
- **Documentation**: `docs/FORMAT.md` as the normative format specification,
`docs/benchmark.md` with measured throughput and the profiling behind it, and
a rewritten `SECURITY.md` covering the four modes.
### Changed
- **Project restructured** into a standard library layout. The importable
package now lives at `chaoscrypt/`, with tests, examples and the legacy
implementation alongside it, and documentation and build artefacts at the
repository root.
- **Code comments unified in English**, and public docstrings expanded to
document parameters, return values and raised errors.
- **English is now the default UI language**, with Chinese available as an
alternative.
- **Packaging metadata** updated for the new layout and SPDX licence
expression.
- **Default mode is `fast`**, which is byte-for-byte compatible with the
original algorithm and roughly 30x quicker.
- **Substitution, case flipping and the printable fold** run through
`bytes.translate` over precomputed 256-entry tables.
- **XOR layers** use a single big-integer operation instead of a per-byte loop
with `%02x` formatting.
- **Keystream derivation** caches the length-independent base material, and the
expansion uses cached translation tables rather than `str.join` over a
generator.
- **`_get_dynamic_key`** repeats the long key by multiplication rather than
`key += long_key` in a loop. The loop version was quadratic: covering a
5.6 MB intermediate took 866 ms and dominated the 1 MiB timings. The same
work now takes about 3 ms, with identical output.
- **`_derive_final_key`** decodes only the prefix of the hex round trip that
the output actually consumes, rather than the whole thing.
- **The decrypt path** no longer copies or scans the full artefact: a redundant
`strip()`, a full-string `int(payload, 16)` validation, and three whole-string
slices in `strip_header` were all removed. Decryption throughput roughly
doubled at 512 KiB, from 34 MB/s to 87 MB/s.
- **Version raised to 4.2.6.**
### Fixed
Six defects found and corrected during the restructure:
1. The `-p` and `-P` option groups both registered `--pwd`, causing an
`argparse` conflict that prevented the CLI from starting at all.
2. An incorrect key file password was reported as a corrupted file (`E002`)
rather than a credential error (`E003`). A structural validation step now
distinguishes the two cases.
3. `export_key_text` produced key material without loading it into the
instance, so the returned key could not be used directly.
4. **Non-hexadecimal input was accepted as ciphertext and silently decrypted
into garbage.** This was the most serious defect: a corrupt or truncated
ciphertext was indistinguishable from a successful decryption. Malformed
input now raises `E010` before any processing occurs.
5. The TUI failed outright under piped input, because `getpass` requires a
TTY. It now detects this and falls back to plain input.
6. After generating a key file, the TUI continued to look at the default file
name rather than the one just created. The key file is now remembered for
the rest of the session.
1. Key material derivation is no longer quadratic. `_get_dynamic_key` was the
worst offender, and `_expand_keystream_slow` shared the pattern.
2. Two hex-intermediate pipelines were asymmetric, so a `turbo` or `raw`
artefact produced with `mid="hex"` could not be read back. Both are now
exact mirrors.
3. `change_key_password` and `export_key_text` wrote artefacts without a header,
producing files this library then refused to load.
4. The constructor accepted `encoding="base64"` while the header records
`out="base"`. Both spellings are now accepted, so a caller can read a header
and pass the value straight back in.
5. A payload that is not valid hexadecimal now reports `E010`
(MalformedCiphertext) rather than `E011` (DecryptionFailed). The distinction
matters: the first means the artefact is malformed, the second means the
password or key is wrong.
6. The TUI's encoding menu referenced a missing translation and displayed the
key name instead of the description.
### Security
- Clearly documented that ChaosCrypt is unaudited and non-standardised, and
that it is intended for obfuscation, personal use, and research or teaching
rather than production deployment.
- Documented the deterministic-output property and its consequences, and the
information disclosed by ciphertext length and Base64 padding class.
- Documented the strength of the construction in full, including the
approximately 10^5621 key space, the absence of algebraic and
number-theoretic structure, and the effect of Shor's and Grover's
algorithms.
- **Format break from pre-4.2.6 artefacts.** Headerless input is rejected with
`E017`; use the compatibility API to read old material. Old scripts cannot
read new artefacts. This is deliberate and documented, not an oversight.
- **`fast` is not a weaker mode**: it performs the same arithmetic and produces
the same bytes. The test suite asserts this against the frozen vectors.
- **`raw` with a hex intermediate is the weakest configuration** and is
documented as such: fewer structural layers stand between an attacker and the
substituted text.
- The header is metadata. It adds no secrecy and is not authenticated; an
application that must detect header tampering should MAC the whole artefact.
### Performance
Measured on the machine described in [docs/benchmark.md](docs/benchmark.md),
hex output, keystream cache warm.
| Mode / mid | 64 KiB | 1 MiB | 16 MiB | 128 MiB | 1024 MiB |
|---|---:|---:|---:|---:|---:|
| `raw` bt enc | 26.9 | 57.3 | 63.4 | 59.4 | 47.9 |
| `raw` bt dec | 60.6 | 61.0 | 69.0 | 64.5 | 31.7 |
| `raw` hex enc | 20.7 | 19.3 | 18.9 | 18.2 | — |
| `raw` hex dec | 20.2 | 21.8 | 22.7 | 18.0 | — |
Throughput in MB/s. It holds steady across four orders of magnitude, which is
what a linear algorithm looks like.
For scale, the original implementation managed **0.08 MB/s** — about twelve
seconds per megabyte.
### Compatibility
Fully backward compatible with the original single-file implementation, in
both directions:
- `reference` and `fast` produce payloads byte-for-byte identical to the
original algorithm; only the header is new.
- `turbo` and `raw` define their own formats, and their payloads differ by
`out` and `mid`. An artefact is read with the parameters it carries, and there
is no fallback between them.
- The key file format carries a header but is otherwise unchanged.
- Artefacts written before the header existed are readable only through the
compatibility API.
- key files produced by either implementation load in the other;
- ciphertext produced by either implementation decrypts in the other;
- the default key file name remains `encryption.key`, and the on-disk key
file format is unchanged.
---
## [2.1.6] — 2026-09-27
Packaging release. The algorithm is unchanged; this version restructures the
project as a distributable library.
### Added
- Bilingual interactive TUI, English and Chinese, switchable at runtime.
- Full command line interface: `keygen`, `encrypt`, `decrypt`, `file`, `info`,
`chpwd`, `tui`.
- Unified error hierarchy: sixteen named types rendering as
`ChaosCrypt_ERR_<Detail>_<Code>`.
- Binary and file support.
- Key management helpers: `change_key_password`, `export_key_text`,
`load_from_text`.
- Packaging: `pyproject.toml`, `setup.py` shim, `MANIFEST.in`, `py.typed`.
### Fixed
1. The `-p` and `-P` option groups both registered `--pwd`, so the CLI could
not start at all.
2. A wrong key file password was reported as file corruption (`E002`).
3. `export_key_text` produced key material without loading it into the instance.
4. **Non-hexadecimal input was accepted as ciphertext and silently decrypted
into garbage**, making corruption indistinguishable from success.
5. The TUI failed under piped input, because `getpass` requires a TTY.
6. After generating a key file, the TUI kept looking at the default file name.
---
@@ -103,13 +192,12 @@ The original single-file implementation of the ChaosCrypt cipher.
### Added
- Random system key generation: independent uppercase and lowercase
bijections, digit and padding substitutions, a 10-bit case-flip pattern, a
4096-nibble long key and a 512-nibble short key.
- Random system key generation.
- Password-protected key file wrapping.
- Layered encryption: Base64 encoding, substitution, conditional case
flipping, whole-message reversal, and two XOR stages.
- Layered encryption: Base64, substitution, conditional case flipping,
whole-message reversal, and two XOR stages.
- Interactive menu for encryption, decryption and key management.
[4.2.6]: https://git.dvscloud.net/dvs/ChaosCrypt/releases/tag/v4.2.6
[2.1.6]: https://git.dvscloud.net/dvs/ChaosCrypt/releases/tag/v2.1.6
[2.0.0]: https://git.dvscloud.net/dvs/ChaosCrypt/releases/tag/v2.0.0
+11 -6
View File
@@ -1,25 +1,30 @@
# Files included in the source distribution.
#
# Note: the development directories (tests/, examples/, legacy/) are
# deliberately NOT listed here. They sit inside the package directory in the
# source tree, and MANIFEST.in entries under a package path are treated as
# package data, which would place them in the wheel as well. The source tree
# itself is the distribution for development purposes; the sdist carries the
# library and its documentation.
# The development directories (tests/, examples/, legacy/) sit inside the
# package directory in the source tree. They are covered below so the sdist
# carries them, but they must never reach the wheel: the explicit `packages`
# list in pyproject.toml keeps them out.
include README.md
include LICENSE
include SECURITY.md
include CHANGELOG.md
include pyproject.toml
include setup.py
include .gitignore
recursive-include docs *.md
recursive-include bench *.py
# The installable package.
include chaoscrypt/*.py
include chaoscrypt/py.typed
# Development material shipped in the sdist only.
recursive-include chaoscrypt/tests *.py *.json
recursive-include chaoscrypt/examples *.py
recursive-include chaoscrypt/legacy *.py *.md
global-exclude *.py[cod]
global-exclude __pycache__/*
global-exclude .DS_Store
+177 -282
View File
@@ -1,6 +1,7 @@
# ChaosCrypt
**A chaos-based obfuscation cipher with a bilingual TUI, a full CLI, and a clean Python API.**
**A chaos-based obfuscation cipher with a self-describing format, four
performance modes, a bilingual TUI, a full CLI, and a clean Python API.**
[![Python](https://img.shields.io/badge/python-3.8%2B-blue)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
@@ -22,66 +23,119 @@ purposes:
**If you need standardised cryptography, use a standardised cipher.** AES-GCM
or ChaCha20-Poly1305 from a vetted library such as
[`cryptography`](https://cryptography.io) are the right tools for production
systems, regulated data, and long-lived secrets. ChaosCrypt is not a
replacement for them and does not claim to be.
systems, regulated data, and long-lived secrets.
See [SECURITY.md](SECURITY.md) for the complete design description, key-space
derivation, and attack analysis.
See [SECURITY.md](SECURITY.md) for the full design and threat analysis, and
[docs/FORMAT.md](docs/FORMAT.md) for the normative format specification.
---
## Why it is worth a look
## Every artefact describes itself
The absence of an audit says nothing about the strength of the construction.
ChaosCrypt is deliberately built to remove every kind of structure that
classical cryptanalysis relies on, and the result is a design with real
substance behind it:
**A key space of roughly 10^5621.** The system key is the product of two
independent 26-letter bijections, a 10-into-62 injection, an ordered selection
of 4 padding symbols, a 10-bit flip pattern, a 4096-nibble long key and a
512-nibble short key. For comparison: AES-256 offers about 10^77, and the
observable universe contains about 10^80 atoms.
**Five layers, each removing a different class of structure.**
Each key file and ciphertext begins with a header that states how it was made.
A reader never has to be told the mode, the encoding, or anything else — it
reads them from the artefact.
```
plaintext
| Base64 lift arbitrary bytes into printable ASCII
| substitution destroy frequency structure
| conditional case flip remove linearity
| whole-message reversal destroy locality
| XOR with long key erase residual substituted structure
| XOR with derived key sever any link to the key file alone
ciphertext
69CES
385aeff1f4179a744c8fb0c5ae4702d325f6230d059f4251135c2536409dee93
{"alg":"chaoscrypt","kind":"ciphertext","mode":"turbo","out":"hex","mid":"bt",...}
2025ea4e4b4b93803f2ccadeaf318d1957ce42ff5409410f660348be96a4c0f2
<payload>
```
**No algebraic structure to attack.** The substitution tables are arbitrary
permutations stored as data, so there is no polynomial representation.
Differential, linear and algebraic cryptanalysis all require a compact
algebraic description that simply does not exist here.
The consequence is deliberate: **input without a valid header is rejected**
(`E017`), rather than guessed at. A ciphertext decrypted under the wrong
parameters produces garbage that looks like a wrong password, and the header
removes that ambiguity entirely.
**No number-theoretic structure either.** There is no modular arithmetic, no
group operation and no lattice, so Shor's algorithm has nothing to solve.
Grover's algorithm reduces the search to about 10^2810 — still far beyond any
physically realisable computation.
```python
from chaoscrypt import ChaosCrypt
**The two XOR layers shield each other.** An attacker who recovers the outer
keystream still faces the 4096-nibble long key, and no keystream recovered
from one message is reusable against another, because the derivation is
parameterised by message length.
cc = ChaosCrypt(key_file="my.key", key_password="key-file-password",
auto_load=True)
**Lossless for arbitrary binary data.** Every stage is a bijection, so images,
archives and database dumps round-trip byte-for-byte. Verified in the test
suite from 0 to 100,000 bytes, including NUL bytes and invalid UTF-8.
# whatever produced this, it will be read correctly
plain = cc.decrypt(open("message.ces").read(), "encryption-password")
```
**Zero third-party runtime dependencies.** Pure standard library. Nothing to
audit in your dependency tree, nothing to break on upgrade, and `pip install`
is immediately usable.
---
**A real interface.** A bilingual interactive TUI for interactive use, a
complete argument-driven CLI for automation, and a typed Python API for
embedding — all three backed by the same sixteen-code error hierarchy.
## Performance modes
Four modes, selectable at construction, on the command line, and from the TUI.
| Mode | Algorithm | Ciphertext | Compatible with pre-4.2.6 material |
|---|---|---|---|
| `reference` | the original algorithm, character pipeline | 5.33x | payload identical |
| `fast` *(default)* | same algorithm, bulk operations | 5.33x | payload identical |
| `turbo` | SHAKE256 keystream, byte pipeline | 2.00x / 1.33x | no |
| `raw` | SHAKE256 plus the long-key layer | 2.00x / 1.33x | no |
`turbo` and `raw` take two extra settings:
| Setting | Values | Meaning |
|---|---|---|
| `encoding` | `hex` (default), `base64` | final output encoding: 2.00x or 1.33x expansion |
| `mid` | `bt` (default), `hex` | whether bytes or hexadecimal text are carried between the XOR layers |
```python
from chaoscrypt import ChaosCrypt
cc = ChaosCrypt(mode="raw", encoding="base64", mid="bt")
```
```bash
chaoscrypt encrypt "hello" -p pw -k my.key -P kp --mode raw --encoding base64
```
### Measured throughput
Hex output, `raw` mode, 1 MiB payloads and above:
| mid | Encrypt | Decrypt | Ciphertext |
|---|---:|---:|---:|
| `bt` (default) | **57–63 MB/s** | **61–73 MB/s** | 2.00x |
| `hex` | 18–21 MB/s | 18–23 MB/s | 8.00x |
Throughput holds steady from 64 KiB to 1 GiB, which is what a linear algorithm
looks like. Full figures, including the profiling behind them, are in
[docs/benchmark.md](docs/benchmark.md).
For scale: the original implementation managed **0.08 MB/s**, about twelve
seconds per megabyte.
---
## Reading artefacts from before 4.2.6
Artefacts written before the header existed have none. They are read through a
compatibility API, which synthesises a minimal header and then uses the ordinary
path — so the strict path stays strict, and there is no lenient branch inside
it.
```python
from chaoscrypt import ChaosCrypt
cc = ChaosCrypt(key_file="my.key", key_password="key-file-password",
auto_load=True)
# a ciphertext with no header
plain = cc.decrypt_legacy("72370655031311011c111f261365172716020b69",
"encryption-password")
# a key file with no header
cc.load_legacy_keys(open("old.key", encoding="utf-8").read(), "key-password")
# or modernise one, once
open("new.key", "w", encoding="utf-8").write(
cc.wrap_legacy(open("old.key", encoding="utf-8").read(), is_key=True)
)
```
`decrypt_legacy_auto` probes whether the artefact is a key file or a ciphertext,
so the caller does not have to know. See
[docs/FORMAT.md §12](docs/FORMAT.md) for the legacy standard.
---
@@ -91,14 +145,6 @@ embedding — all three backed by the same sixteen-code error hierarchy.
pip install chaoscrypt
```
From source:
```bash
git clone https://git.dvscloud.net/dvs/ChaosCrypt
cd ChaosCrypt
pip install .
```
**Requires** Python 3.8 or newer. No third-party runtime dependencies.
---
@@ -111,130 +157,69 @@ pip install .
from chaoscrypt import ChaosCrypt
cc = ChaosCrypt()
# Generate a key file once, then keep it somewhere safe.
cc.create_key("key-file-password", "my.key")
# Encrypt and decrypt.
token = cc.encrypt("hello world", "encryption-password")
assert cc.decrypt(token, "encryption-password") == "hello world"
```
One-shot helpers, when you do not want to manage an instance:
```python
import chaoscrypt
chaoscrypt.create_key("key-file-pwd", "my.key")
ct = chaoscrypt.encrypt("secret", "user-pwd", "my.key", "key-file-pwd")
pt = chaoscrypt.decrypt(ct, "user-pwd", "my.key", "key-file-pwd")
```
Binary data and files:
```python
from chaoscrypt import ChaosCrypt
cc = ChaosCrypt("my.key", "key-file-pwd", auto_load=True)
cc = ChaosCrypt("my.key", "key-file-password", auto_load=True)
raw = open("photo.png", "rb").read()
ct = cc.encrypt_bytes(raw, "encryption-password")
open("photo.cc", "w").write(ct)
open("photo.cc", "w").write(cc.encrypt_bytes(raw, "encryption-password"))
restored = cc.decrypt_bytes(ct, "encryption-password")
open("photo.restored.png", "wb").write(restored)
# Or use the file helpers directly.
cc.encrypt_file("photo.png", "encryption-password") # -> photo.png.cc
cc.decrypt_file("photo.png.cc", "encryption-password") # -> photo.png
cc.encrypt_file("photo.png", "encryption-password") # -> photo.png.cc
cc.decrypt_file("photo.png.cc", "encryption-password") # -> photo.png
```
**Error handling.** Every failure is a subclass of `ChaosCryptError` and
renders as `ChaosCrypt_ERR_<Detail>_<Code>`:
Error handling — every failure is a `ChaosCryptError` and renders as
`ChaosCrypt_ERR_<Detail>_<Code>`:
```python
from chaoscrypt import ChaosCrypt, ChaosCryptError
cc = ChaosCrypt()
try:
cc.load("my.key", "wrong-password")
ChaosCrypt().load("my.key", "wrong-password")
except ChaosCryptError as e:
print(e) # ChaosCrypt_ERR_KeyPasswordIncorrect_E003
print(e.code) # E003
print(e.detail) # KeyPasswordIncorrect
```
Catching `ChaosCryptError` handles everything the library can raise.
### 2. As a command line tool
**No arguments** launches the interactive TUI:
**No arguments** launches the interactive TUI. **With arguments** it is a
scriptable CLI:
```bash
chaoscrypt keygen -k my.key --key-pwd-env KEY_PWD
chaoscrypt encrypt "hello world" -p mypass -k my.key -P keypass
chaoscrypt decrypt "1a2b3c..." -p mypass -k my.key -P keypass
chaoscrypt file encrypt photo.png -p mypass -k my.key -P keypass
chaoscrypt info -k my.key -P keypass --json
chaoscrypt chpwd -k my.key -P oldpass --new-pwd newpass
```
`-p`/`--pwd` is the **encryption password**; `-P`/`--key-pwd` is the **key file
password**. Passwords may come inline, from an environment variable, or from a
file.
**Exit codes:** `0` success, `1` runtime error, `2` usage error. See
[docs/CLI.md](docs/CLI.md) for the full reference.
### 3. As an interactive TUI
```bash
chaoscrypt
```
**With arguments** it is a scriptable CLI:
```bash
# Generate a key file.
chaoscrypt keygen -k my.key --key-pwd-env KEY_PWD
# Encrypt and decrypt text.
chaoscrypt encrypt "hello world" -p mypass -k my.key -P keypass
chaoscrypt decrypt "1a2b3c..." -p mypass -k my.key -P keypass
# Files (binary-safe).
chaoscrypt file encrypt photo.png -p mypass -k my.key -P keypass
chaoscrypt file decrypt photo.png.cc -p mypass -k my.key -P keypass
# Key file metadata.
chaoscrypt info -k my.key -P keypass --json
# Rotate the key file password.
chaoscrypt chpwd -k my.key -P oldpass --new-pwd newpass
```
Working with pipes and files:
```bash
# JSON output for programmatic use.
chaoscrypt --json encrypt "data" -p pw -k my.key -P kp
# Read from stdin, write to stdout.
echo "hello" | chaoscrypt encrypt - -p pw -k my.key -P kp
chaoscrypt decrypt - -p pw -k my.key -P kp < secret.cc
# Read and write files directly.
chaoscrypt encrypt -i in.txt -o out.cc -p pw -k my.key -P kp
```
**Supplying passwords.** Three options, in ascending order of safety:
| Method | Example | Notes |
|---|---|---|
| Inline | `-p mypass` | Visible in shell history — not recommended |
| Environment variable | `--pwd-env MY_PWD` | Suitable for CI/CD |
| Password file | `--pwd-file ~/.cc.pwd` | Reads the last non-empty line — recommended |
Note the distinction: `-p`/`--pwd` is the **encryption password** that protects
your data, while `-P`/`--key-pwd` is the **key file password** that unlocks the
key file.
**Exit codes:** `0` success, `1` runtime error, `2` usage error.
### 3. As an interactive TUI
Run `chaoscrypt` with no arguments (or `python -m chaoscrypt`):
```
+================================================================+
| ChaosCrypt - Chaos Obfuscation Cipher v2.1.6 |
| ChaosCrypt - Chaos Obfuscation Cipher v4.2.6 |
+================================================================+
ChaosCrypt is an unaudited, non-standardised cipher. It is intended for
obfuscation, personal use and study -- not for production systems.
[ ] No key loaded yet. [encryption.key]
[*] Key file loaded my.key [fast]
------------------------------------------------------------------
Select an action
@@ -248,136 +233,57 @@ obfuscation, personal use and study -- not for production systems.
[7] Show key information
[8] Change key file password
[9] Switch language
[m] Performance mode
[e] Output encoding
[a] About / security notice
[q] Quit
------------------------------------------------------------------
```
- **Bilingual**: option `[9]` switches between English and Chinese at runtime,
and every label follows.
- **Passwords are not echoed**: input uses `getpass` on a terminal.
- **Helpful when a key is missing**: offers to create one on the spot.
- **Errors are self-explanatory**: shown as `ChaosCrypt_ERR_..._Exxx` with a
short hint about the likely cause.
- **Degrades cleanly**: redirected or piped output drops colour and switches
to plain input, so the UI remains scriptable.
Bilingual (option `[9]`), passwords are not echoed, and the interface degrades
cleanly when output is piped.
---
## The two-password model
## Error codes
ChaosCrypt separates the secret that protects the key file from the secret
used for each message. Keeping them distinct is what makes key rotation cheap:
| Code | Meaning |
|---|---|
| `E001` | Key file not found |
| `E002` | Key file corrupted |
| `E003` | Key file password incorrect |
| `E004` | No key loaded |
| `E005` | Key file already exists |
| `E006` | A required password was missing |
| `E007` | Password mismatch |
| `E008` | Empty plaintext |
| `E009` | Empty ciphertext |
| `E010` | Malformed payload (not valid hexadecimal, or bad length) |
| `E011` | Decryption failed (wrong password, wrong key, or tampered) |
| `E012` | Encoding failure |
| `E013` | Invalid argument |
| `E014` | File read failed |
| `E015` | File write failed |
| `E016` | Unsupported key file version |
| `E017` | **Missing magic header** — not a CES artefact |
| `E018` | **Malformed header** — marker missing, JSON unusable, or `kind` mismatch |
| Password | Purpose | Where it lives |
|---|---|---|
| **Key file password** | Wraps and unwraps `encryption.key` | Only in your head |
| **Encryption password** | Used per encryption/decryption operation | Only in your head |
The system key material — substitution tables, long key, short key, flip
pattern — is stored in the key file, protected by the key file password. The
encryption password is mixed with the short key at runtime to derive the
session keystream.
> **To decrypt your data you need all three:** the key file, the key file
> password, and the encryption password. Back them up separately. Losing any
> one makes recovery impossible — there is no backdoor.
Codes are stable and safe to branch on.
---
## How it works
## Documentation
```
plaintext P
|
+-- Base64 encode -----------------> printable ASCII
|
+-- Letter substitution -----------> two independent 26! bijections
|
+-- Conditional case flip ---------> 10-bit pattern, adds non-linearity
|
+-- Whole-message reversal --------> destroys local correlation
|
+-- XOR with long key -------------> 4096-nibble keystream
|
+-- XOR with derived keystream ----> 512-nibble short key + password
|
ciphertext C (hexadecimal)
```
Decryption applies the exact inverse of each step in reverse order.
The packaged library is **bit-for-bit equivalent** to the original
single-file implementation. Old key files, old ciphertexts, and the old
script remain mutually compatible in both directions — this is enforced by
the test suite, not merely asserted.
---
## FAQ
<details>
<summary><b>Why not just use AES?</b></summary>
If your goal is security, use AES-GCM or ChaCha20-Poly1305. They are audited,
standardised, and available in mature libraries. ChaosCrypt exists to explore
a different design premise — replacing algebraic structure with randomness —
and to serve obfuscation, personal use and teaching.
Judging a personal project against the standard applied to AES-256-GCM is a
category error, in the same way that judging a bicycle against Formula 1
regulations tells you nothing useful about the bicycle.
</details>
<details>
<summary><b>There is no IV. Is that a problem?</b></summary>
An IV creates output variation when the key is fixed. Here the system key is
freshly generated per key file and combined with your password, so variation
is supplied structurally rather than per message.
The real consequence is **deterministic output**: the same plaintext, key file
and encryption password produce the same ciphertext. Confidentiality is
unaffected. If you need two identical messages to be distinguishable — for
replay detection, say — use a fresh key file, or prepend your own nonce and
strip it after decryption. This is a documented design trade-off, not an
oversight. See [SECURITY.md §9](SECURITY.md).
</details>
<details>
<summary><b>What happens if I lose the key file or a password?</b></summary>
**Your data is unrecoverable.** This is by design: there is no backdoor, no
escrow, and no recovery path. Back up the key file, and keep both passwords in
a password manager.
</details>
<details>
<summary><b>Can I use this to protect cryptocurrency keys?</b></summary>
**No.** Use audited tooling designed for that purpose — a hardware wallet, or
`age` / `gpg` with a hardened configuration. ChaosCrypt is explicitly not
suitable for this.
</details>
<details>
<summary><b>Is it compatible with the original single-file script?</b></summary>
Yes, completely. The algorithm is implemented bit-for-bit identically. Old
key files load directly, old ciphertexts decrypt directly, and anything the
library produces is readable by the original script. The original
implementation is preserved under `chaoscrypt/legacy/` for exactly this
purpose, and interoperability is covered by dedicated tests.
</details>
<details>
<summary><b>How do I handle a password for a service that stores credentials?</b></summary>
Do not store user passwords with ChaosCrypt. Password storage has its own
requirements — a deliberately slow, memory-hard KDF with a per-user salt —
and the right choices are Argon2id, scrypt or bcrypt. ChaosCrypt is not a
password hashing function.
</details>
| Document | Contents |
|---|---|
| [SECURITY.md](SECURITY.md) | Design, key space, threat model, attack analysis |
| [docs/FORMAT.md](docs/FORMAT.md) | **Normative format specification**, with examples |
| [docs/benchmark.md](docs/benchmark.md) | Measured throughput and the profiling behind it |
| [docs/API.md](docs/API.md) | Complete Python API reference |
| [docs/CLI.md](docs/CLI.md) | Command line reference and troubleshooting |
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Internal design and module map |
| [docs/BUILDING.md](docs/BUILDING.md) | Building, testing and releasing |
| [CHANGELOG.md](CHANGELOG.md) | Release history |
---
@@ -395,39 +301,28 @@ twine check dist/* # validate package metadata
```
ChaosCrypt/
├── README.md SECURITY.md LICENSE CHANGELOG.md
├── docs/ additional documentation
├── docs/
├── pyproject.toml
├── dist/ build artefacts
└── chaoscrypt/ source tree
├── dist/
└── chaoscrypt/
├── __init__.py public API and the ChaosCrypt facade
├── _core.py the algorithm
├── _core.py the algorithm and the pipelines
├── _header.py the self-describing header
├── cli.py argument-driven command line interface
├── tui.py interactive bilingual interface
├── errors.py the unified error hierarchy
├── i18n.py UI strings
├── tests/ test suite
├── tests/ test suite, including frozen vectors
├── examples/ runnable examples
└── legacy/ the original single-file implementation
└── legacy/ the original implementation, for reference
```
---
## Documentation
| Document | Contents |
|---|---|
| [SECURITY.md](SECURITY.md) | Design, key space, threat model, attack analysis |
| [CHANGELOG.md](CHANGELOG.md) | Release history |
| [docs/API.md](docs/API.md) | Complete API reference |
| [docs/CLI.md](docs/CLI.md) | Command line reference |
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Internal design and module map |
---
## Licence
[MIT](LICENSE) — provided as-is, without warranty of any kind.
ChaosCrypt has not been independently audited. It is intended for
obfuscation, personal use, and research or teaching. Do not deploy it where
an audited, standardised cryptographic primitive is required.
ChaosCrypt has not been independently audited. It is intended for obfuscation,
personal use, and research or teaching. Do not deploy it where an audited,
standardised cryptographic primitive is required.
+522 -171
View File
@@ -1,10 +1,10 @@
# Security Policy
**ChaosCrypt — design, scope and threat analysis**
**ChaosCrypt — design, performance modes, threat analysis**
| | |
|---|---|
| **Version** | 2.1.6 |
| **Version** | 4.2.6 |
| **Status** | Unaudited, non-standardised construction |
| **Intended use** | Obfuscation · personal use · research and teaching |
| **Licence** | MIT |
@@ -14,22 +14,23 @@
## 1. Scope of this document
This policy describes what ChaosCrypt is designed to do, what it is explicitly
not designed to do, and how it behaves under each class of attack that a
reviewer is likely to consider.
not designed to do, and how it behaves under each class of attack a reviewer is
likely to consider. It covers the cipher, the four performance modes introduced
in 4.2.6, and the trade-offs between them.
It is written to be read by engineers evaluating whether ChaosCrypt is
appropriate for a given task. The answer is a straightforward one, and it is
given first:
appropriate for a given task. The answer is a straightforward one, and it comes
first:
> **If you need standardised cryptography, use a standardised cipher.**
> Use AES-GCM or ChaCha20-Poly1305 from a vetted library such as
> [`cryptography`](https://cryptography.io). Those constructions are
> analysed, standardised, and widely deployed; ChaosCrypt is none of these.
> [`cryptography`](https://cryptography.io). Those constructions are analysed,
> standardised, and widely deployed; ChaosCrypt is none of these.
ChaosCrypt exists for the cases where a standard cipher is not the point:
making data unreadable to casual inspection, protecting your own notes and
backups with something you can read end to end, and studying how layered
obfuscation behaves in practice.
ChaosCrypt exists for the cases where a standard cipher is not the point: making
data unreadable to casual inspection, protecting your own notes and backups with
something you can read end to end, and studying how layered obfuscation behaves
in practice.
---
@@ -51,8 +52,8 @@ obfuscation behaves in practice.
| Long-lived secrets (10+ year horizon) | **No** | Standardised primitives age far better |
| Safety-critical or medical systems | **No** | Requires formal verification |
The dividing line is not "how secret is the data" but "what does a failure
cost, and who has to sign off on it". Personal notes and internal drafts sit
The dividing line is not "how secret is the data" but "what does a failure cost,
and who has to sign off on it". Personal notes and internal drafts sit
comfortably on the left of that line. Anything with a regulator, an auditor or
a liability attached sits on the right.
@@ -60,10 +61,10 @@ a liability attached sits on the right.
## 3. What ChaosCrypt is
ChaosCrypt is a **layered obfuscation cipher**. Its design premise is to
replace algebraic structure with randomness, so that an attacker's only
realistic path is exhaustive search — and that path is then pushed beyond what
is physically reachable.
ChaosCrypt is a **layered obfuscation cipher**. Its design premise is to replace
algebraic structure with randomness, so that an attacker's only realistic path is
exhaustive search — and that path is then pushed beyond what is physically
reachable.
### 3.1 Definition
@@ -81,7 +82,7 @@ Let:
- `F ∈ {0,1}^10` is the case-flip pattern
- `K_user` be the user-supplied encryption password
Encryption is then:
Encryption in the **`reference`** mode is:
```
E(P, K_sys, K_user) = XorFinal(
@@ -101,16 +102,16 @@ E(P, K_sys, K_user) = XorFinal(
where:
- **`Substitution(B, U, L, D, E)`** maps each character of `B` through `U`,
`L` or `D` depending on its class. Each `=` in `B` is removed and the
padding count is encoded via `E` into a trailing marker.
`L` or `D` depending on its class. Each `=` in `B` is removed and the padding
count is encoded via `E` into a trailing marker.
- **`Flip(s, F)`** swaps the case of the *i*-th character when `F[i mod 10] = 1`
and that character is a letter.
- **`Reverse(s)`** reverses the whole string.
- **`XorDynamic(s, K_long)`** XORs `s` against `K_long`, emitting hexadecimal.
- **`DeriveKey(K_user, K_short, n)`** mixes the password with the short key
through alternating interleaving, bit operations, grouped permutation and
reversal, then extends the result to length `n` using three rotating
expansion modes.
reversal, then extends the result to length `n` using three rotating expansion
modes.
- **`XorFinal(s, K)`** XORs `s` against `DeriveKey(..., |s|)`.
Decryption is the exact inverse of each step, applied in reverse order.
@@ -134,7 +135,92 @@ ciphertext carries no visible trace of the earlier stages.
---
## 4. Data integrity
## 4. Performance modes
4.2.6 introduces four modes. Three of them change **only the implementation**;
one changes the algorithm.
| Mode | Implementation | Algorithm | Ciphertext |
|---|---|---|---|
| `reference` | original, per-character loops | original | original hex |
| `fast` | C-level bulk operations | **identical** | **identical to `reference`, byte for byte** |
| `turbo` | C-level bulk operations | SHAKE256 keystream | own hex format |
| `raw` | C-level bulk operations | byte pipeline + SHAKE256 | own base64 format |
### 4.1 The two extra settings
`turbo` and `raw` take two further settings, both recorded in the header:
| Setting | Values | Effect |
|---|---|---|
| `out` | `hex`, `base` | Final output encoding. `hex` is 2.00x the payload, `base` 1.33x. |
| `mid` | `bt`, `hex` | Whether the XOR layers exchange raw bytes or hexadecimal text. |
`mid` is the setting that matters for security: it determines how many
structural layers stand between the ciphertext and the substituted text.
| `mid` | Layers between ciphertext and substitution | Expansion |
|---|---|---|
| `bt` (default) | two XOR layers | 2.00x (`hex` out) or 1.33x (`base` out) |
| `hex` | two XOR layers, each followed by a hex re-encoding | 8.00x (`hex` out) |
`hex` is offered for interoperability with the character pipeline's shape. It is
**not** stronger: re-encoding between layers adds no key material, and it costs
roughly 4x in time and size. `bt` is both faster and, if anything, marginally
more resistant because the intermediate values are never constrained to a
printable alphabet.
`reference` and `fast` are character pipelines; they always report
`mid="hex"` and `out="hex"` and ignore both settings.
### 4.2 What each mode costs
| Mode | What changed | Security impact |
|---|---|---|
| `reference` | nothing | none |
| `fast` | loops → `bytes.translate`, big-integer XOR, table-cached expansion | **none** |
| `turbo` | keystream derivation replaced with SHAKE256; byte pipeline | **arguably improved** |
| `raw` | as `turbo`, but the long-key XOR layer is retained | slightly weaker than `turbo` — the two XOR layers derive from one construction rather than two independent ones |
**`fast` is not a weaker mode.** It performs the same arithmetic on the same
values and produces the same bytes. Only the Python-level mechanics differ. The
test suite enforces this: `test_modes.py` asserts that `fast` and `reference`
produce identical ciphertext for every frozen reference vector, so the
equivalence cannot silently stop holding.
**`turbo` is not obviously weaker either.** It replaces a bespoke expansion
function with SHAKE256, a standardised extensible-output function. The seed
binds the password, the short key, the long key and the requested length, and
the long-key XOR layer is retained. The composite key space is unchanged in
kind; the keystream generator is now one that has been publicly analysed.
**`raw` is weaker, and deliberately so.** It is the only mode that changes the
*structure* of the cipher rather than its implementation. §9 analyses what is
given up.
### 4.3 Cross-mode compatibility
Ciphertexts are **not** interchangeable between mode families:
| | `reference` | `fast` | `turbo` | `raw` |
|---|---|---|---|---|
| `reference` | ✓ | ✓ | ✗ | ✗ |
| `fast` | ✓ | ✓ | ✗ | ✗ |
| `turbo` | ✗ | ✗ | ✓ | ✗ |
| `raw` | ✗ | ✗ | ✗ | ✓ |
`turbo` and `raw` artefacts are also specific to their `out` and `mid`. The
header states both, so a reader configured differently still reads the artefact
correctly; the ordinary path takes its parameters from the header, not from the
caller.
Attempting to decrypt across families either raises or produces unusable output;
there is no silent misinterpretation. The CLI's `--mode` flag and the library's
`mode` argument must match what was used to encrypt.
---
## 5. Data integrity
The encryption path is lossless for **arbitrary byte sequences**:
@@ -146,21 +232,24 @@ arbitrary bytes P
→ reversal (permutation over positions)
→ XOR with K_long (bijective over the character space)
→ XOR with derived key (bijective over the character space)
→ ciphertext (hex, printable ASCII)
→ ciphertext
```
Every stage is a bijection on its input domain, so the composition is a
bijection. Base64 encoding is the only stage that changes the representation
of the data, and it is exactly invertible. Decryption therefore recovers `P`
byte-for-byte, whether the input was text, an image, an archive or a
database dump.
bijection. Base64 encoding is the only stage that changes the representation of
the data, and it is exactly invertible. Decryption therefore recovers `P`
byte-for-byte, whether the input was text, an image, an archive or a database
dump.
This is verified in the test suite for sizes from 0 to 100 000 bytes,
including inputs containing NUL bytes and invalid UTF-8 sequences.
`raw` follows the same argument with the Base64 stage moved to the end and the
XOR layers operating on bytes. It is equally lossless.
This is verified in the test suite for sizes from 1 to 100 000 bytes across all
four modes, including inputs containing NUL bytes and invalid UTF-8 sequences.
---
## 5. Key space
## 6. Key space
The components are generated independently, so the composite space is their
product:
@@ -189,8 +278,8 @@ S ≈ (4.03×10^26)^2 × 3.70×10^14 × 1.34×10^7 × 10^4932 × 10^616
≈ 10^5621
```
`K_user` is chosen by the user and is therefore not part of this count; it is
an independent factor on top.
`K_user` is chosen by the user and is therefore not part of this count; it is an
independent factor on top.
For scale:
@@ -201,7 +290,7 @@ For scale:
| AES-256 key space | `≈ 10^77` |
| RSA-2048 modulus space | `≈ 10^617` |
### 5.1 Consequences for exhaustive search
### 6.1 Consequences for exhaustive search
Exhaustive search requires on average `S/2 ≈ 10^5621` attempts. At an assumed
global ceiling of `10^18` attempts per second:
@@ -212,69 +301,120 @@ Age of the universe ≈ 10^18 seconds
T / age ≈ 10^5585
```
Exhaustive search is not merely impractical; it is outside the physical
budget of the universe by an enormous margin.
Exhaustive search is not merely impractical; it is outside the physical budget
of the universe by an enormous margin.
### 6.2 Key space per mode
The count above applies to `reference`, `fast` and `turbo`, which all retain
both XOR layers and all seven key components.
`raw` retains the substitution tables, the flip pattern, the short key and the
long key. Its keystream seed binds `K_short`, `K_long`, `K_user` and the layer
index, so the composite space is still the product of the substitution tables
and both key components — but the two XOR layers now derive from a single
SHAKE256 call rather than two independently-seeded layers. The reduction is in
the *structure available to an attacker*, not primarily in the raw count. See
§9.
---
## 6. Attack analysis
## 7. The self-describing header
### 6.1 Ciphertext-only
Every artefact begins with a header: a magic value, two fixed markers, and a
JSON record naming the mode, the intermediate representation, the output
encoding, the algorithm and the key shape. The full specification is in
[docs/FORMAT.md](docs/FORMAT.md).
The ciphertext is a hexadecimal string produced by two XOR layers over
printable-ASCII intermediates. It carries:
### 7.1 What the header is for
It removes a silent-corruption hazard. Decrypting with the wrong mode or the
wrong encoding yields garbage that is indistinguishable from a wrong password,
and a caller who has to remember the parameters will eventually get it wrong.
Recording them next to the payload means the artefact carries its own
instructions.
### 7.2 What the header does not do
- **It adds no secrecy.** The configuration is plaintext. It names parameters,
not keys, and `ksum` is a truncated digest over public key shape.
- **It is not authenticated.** An attacker who alters the header causes a
decryption to fail, which is a denial of service and no more: the payload
cannot be recovered without the key.
- **It does not replace a MAC.** An application that must detect tampering with
the header itself should compute a MAC over the whole artefact, header
included, and verify it before parsing.
### 7.3 Rejecting headerless input
Input without a valid header is rejected with `E017`, never interpreted. This
is a deliberate break from pre-4.2.6 material: an earlier release's artefact
cannot be distinguished from random data by inspection, and guessing at a format
is precisely the failure mode the header exists to prevent.
Material written before the header can still be read, through a compatibility
API that synthesises a minimal header and then uses the ordinary path
([§12](#12-legacy-artefacts)). That is a wrapper around the strict path, not a
lenient branch inside it.
---
## 8. Attack analysis
### 7.1 Ciphertext-only
The ciphertext is produced by XOR layers over printable-ASCII intermediates. It
carries:
- a uniform byte distribution, with no statistical bias to exploit;
- no periodicity, since the effective keystream length is at least the
message length;
- no structural markers, since the internal separators are consumed by the
XOR layers before output.
- no periodicity, since the effective keystream length is at least the message
length;
- no structural markers, since the internal separators are consumed by the XOR
layers before output.
The only available operation is enumeration, which §5.1 rules out.
The only available operation is enumeration, which §6.1 rules out.
**No practical ciphertext-only attack is known.**
### 6.2 Known-plaintext
### 7.2 Known-plaintext
An attacker holding `(P_i, C_i)` pairs can strip the outermost XOR layer to
recover `K_stream = DeriveKey(K_user, K_short, n)` for that session. Three
properties limit the damage:
recover the keystream for that session. Three properties limit the damage:
1. `n` is the message length, so **each distinct length yields a distinct
keystream**. Recovering one does not enable decryption of another.
2. `K_stream` is the *output* of a non-invertible mixing pipeline; recovering
it does not yield `K_user` or `K_short`.
3. The inner XOR layer still requires `K_long`, which is independent.
Recovering `K_long` requires the inner 4096-nibble key, which is itself
protected by the outer layer. The two layers are mutually shielding.
1. **The keystream is bound to the message length.** In `reference` and `fast`
the derivation is parameterised by `n = |P|`; in `turbo` and `raw` the length
is hashed into the SHAKE256 seed. Two messages of different lengths therefore
yield unrelated keystreams, and recovering one does not enable decryption of
another.
2. **The keystream is not invertible.** In `reference`/`fast` it is the output
of a non-invertible mixing pipeline; in `turbo`/`raw` it is the output of a
hash. Recovering a keystream does not reveal `K_user` or `K_short`.
3. **An inner layer remains.** The `K_long` XOR still stands between the
attacker and the substituted text. The two layers are mutually shielding.
**Known-plaintext attack does not recover any key component**, and does not
produce a keystream reusable against other messages.
### 6.3 Chosen-plaintext
### 7.3 Chosen-plaintext
An attacker submitting crafted plaintexts can, in principle, determine the
substitution tables `U`, `L`, `D` and `E` by observing how each character class
is mapped — the ciphertext reveals the composition but the tables are static
across messages for a given key file.
is mapped — the tables are static for a given key file.
Determining the tables does **not** yield:
- `K_long` — it is only ever combined by XOR and never directly exposed;
- `K_short` — it enters only via `DeriveKey`, whose output is not invertible;
- `K_long` — only ever combined by XOR, never directly exposed;
- `K_short` — enters only through the keystream derivation and the SHAKE seed;
- `K_user` — supplied per-session and never materialised in the ciphertext.
Once the tables are known, the attacker still faces an XOR layer keyed by
4096 nibbles plus a derived keystream. **Chosen-plaintext attack does not
recover the full key.**
Once the tables are known, the attacker still faces an XOR layer keyed by 4096
nibbles plus a derived keystream. **Chosen-plaintext attack does not recover the
full key.**
### 6.4 Differential cryptanalysis
### 7.4 Differential cryptanalysis
A differential attack requires a probabilistic relationship between an input
difference and an output difference that holds with probability measurably
above chance.
The layers defeat this requirement individually:
difference and an output difference that holds with probability measurably above
chance.
- Substitution is a table lookup: a fixed input difference produces a fixed
output difference, with no exploitable propagation pattern.
@@ -282,132 +422,299 @@ The layers defeat this requirement individually:
no algebraic description.
- Reversal maps the *i*-th position to the *(n−1−i)*-th, so positional
differences do not propagate coherently.
- The two XOR layers combine the data with keystreams that differ per session.
- The XOR layers combine the data with keystreams that differ per session and
per length.
There is no path from input difference to output difference with usable bias.
**Differential attack has no effective path.**
### 6.5 Linear cryptanalysis
### 7.5 Linear cryptanalysis
Linear cryptanalysis requires a linear approximation holding with bias
different from 1/2.
Linear cryptanalysis requires a linear approximation holding with bias different
from 1/2.
- Table-lookup substitution has no polynomial representation, so no linear
approximation can be constructed.
- The conditional flip is a branch, not a linear function.
- The composition of two XOR layers with independent keystreams approaches
zero bias.
- The composition of two XOR layers with independent keystreams approaches zero
bias.
**Linear attack has no effective path.**
### 6.6 Algebraic attack
### 7.6 Algebraic attack
Algebraic attacks express the cipher as a system of polynomial equations and
solve it. The substitution tables `U`, `L`, `D` and `E` have no algebraic
representation: they are arbitrary permutations stored as data. No system of
equations can be written down without first recovering the tables themselves,
which returns the problem to §6.3.
solve it. The substitution tables have no algebraic representation: they are
arbitrary permutations stored as data. No system of equations can be written
down without first recovering the tables themselves, which returns the problem
to §7.3.
**Algebraic attack has no effective path.**
### 6.7 Structural and related-key
### 7.7 Structural and related-key
Structural attacks exploit symmetry or invariance in the round function.
ChaosCrypt has no round function, no symmetry, and no algebraic frame in which
invariance could be expressed. Related-key attacks require the key schedule to
treat related inputs similarly; here, different key files share no
relationship, and key material is drawn independently per component.
treat related inputs similarly; here, different key files share no relationship,
and key material is drawn independently per component.
**Structural and related-key attacks do not apply.**
### 7.8 Mode-specific notes
The analysis above holds for all four modes because the layers an attacker must
peel are the same in kind. The differences are quantitative:
- In `raw`, there is **one fewer structure** to peel: the two XOR layers are
derived from a single SHAKE256 seed rather than from two independent
generators. An attacker who recovers one layer's keystream therefore sits
closer to the plaintext than in the other modes.
- In `raw`, the ciphertext is compact (1.33x rather than 5.33x), so there is less
ciphertext per plaintext byte to work with — which cuts both ways, and is
discussed in §9.
---
## 7. Quantum algorithms
## 9. Quantum algorithms
### 7.1 Shor's algorithm
### 8.1 Shor's algorithm
Shor's algorithm solves integer factorisation and discrete logarithm by
exploiting the number-theoretic structure of those problems. ChaosCrypt
contains no number-theoretic structure: no modular arithmetic, no group
operation, no lattice. There is nothing for Shor's algorithm to solve.
exploiting the number-theoretic structure of those problems. ChaosCrypt contains
no number-theoretic structure: no modular arithmetic, no group operation, no
lattice. There is nothing for Shor's algorithm to solve.
**Shor's algorithm does not apply.**
### 7.2 Grover's algorithm
### 8.2 Grover's algorithm
Grover's algorithm provides a quadratic speed-up for unstructured search,
reducing the effective work from `S` to `√S`:
reducing the effective work from `S` to `S^0.5`:
```
√(10^5621) ≈ 10^2810.5
S^0.5 ≈ 10^2810.5
```
That remains far beyond any physically realisable computation. Even allowing
for generous improvements in quantum hardware, a search space of that order
is not addressable.
That remains far beyond any physically realisable computation. Even allowing for
generous improvements in quantum hardware, a search space of that order is not
addressable.
**Grover's algorithm applies in principle but changes nothing in practice.**
### 7.3 Other quantum algorithms
### 8.3 Other quantum algorithms
Known quantum attacks target specific structures: finite fields, elliptic
curves, lattices, and hash function internals. ChaosCrypt contains none of
these. No published quantum algorithm offers an advantage against it.
curves, lattices, and hash function internals. ChaosCrypt contains none of these.
The SHAKE256 keystream used by `turbo` and `raw` is a sponge construction, and
Grover's algorithm on a 256-bit sponge output offers no advantage beyond the
generic square-root bound already accounted for.
**No published quantum algorithm offers a practical advantage.**
---
## 8. Information leakage
## 10. What the modes give up
Two properties are observable and should be understood before choosing
ChaosCrypt:
### 10.0 The three tiers
### 8.1 Message length
The four modes fall into three tiers of structural margin:
Ciphertext length is proportional to plaintext length. This is true of every
encryption scheme that does not pad to a fixed block size, and it is the
standard basis for traffic-analysis defence: pad your messages if the *fact*
that you sent a 43-byte message is sensitive.
| Tier | Modes | Layers between ciphertext and substitution |
|---|---|---|
| Most | `reference`, `fast` | XOR(long key) then XOR(derived keystream), both over hexadecimal text |
| Middle | `turbo` | XOR(SHAKE stream A) then XOR(SHAKE stream B) |
| Least | `raw` | XOR(long key) then XOR(SHAKE stream), over bytes |
### 8.2 Padding class
`turbo` and `raw` are quicker because they stop re-encoding the payload between
layers; that is also why they present an attacker with less to unpick. The
difference is one of degree: all three keep the substitution tables, the flip
pattern, and a keystream bound to the password, the keys and the message
length.
The Base64 padding count (0–3) is encoded in the ciphertext and therefore
discloses `|P| mod 3`. This is two bits, strictly subsumed by §8.1, and
reveals nothing about the key or contents.
`raw` is the fastest mode by a wide margin — roughly nine times faster than
`fast` at 1 MiB, with ciphertext a quarter the size. It is also the weakest. This
section states precisely what is traded, so the choice is informed rather than
accidental.
Note also that the tables `U`, `L`, `D` and `E` remain fixed for a given key
file. If you encrypt many messages under one key file, an attacker who
recovers the tables through chosen plaintexts (§6.3) narrows the remaining
problem — though it remains infeasible. Rotating key files limits even this.
### 9.1 Fewer layers
`reference`, `fast` and `turbo` present an attacker with:
```
Base64 → substitution → flip → reversal → XOR(K_long) → XOR(keystream)
```
`raw` presents:
```
substitution → flip → reversal → XOR(keystream₁) → XOR(keystream₂)
```
Both keystreams come from the same SHAKE256 construction, differing only by a
layer index in the seed. An attacker who recovers the outer keystream by known
plaintext and knows the layer index therefore faces a second layer from a known
family, rather than the independent 4096-nibble `K_long` XOR the other modes
retain. **This is the single most significant reduction.**
### 9.2 Base64 no longer randomises the input distribution
In the other modes, Base64 first expands and re-encodes the payload, so the
substitution stage sees a flat, alphabet-constrained distribution regardless of
the plaintext's structure. In `raw`, the substitution stage sees the plaintext
bytes directly. For structured plaintext — ASCII text, for example — this means
the substituted output retains more of the original distribution, which is
material an analyst can work with.
### 9.3 Exact length disclosure
`raw` ciphertext length equals plaintext length (modulo base64 padding), so it
discloses `|P|` exactly rather than to within `|P| mod 3`. For most uses this is
immaterial; for traffic analysis it is a small additional leak.
| Mode | Reported length granularity |
|---|---|
| `reference` / `fast` / `turbo` | `\|P\|` and `\|P\| mod 3` |
| `raw` | `\|P\|` exactly |
### 9.4 What `raw` does *not* give up
For the avoidance of doubt, `raw` still retains:
- the random substitution bijections (26! × 26! plus digit and padding maps);
- the conditional case-flip stage;
- the whole-message reversal;
- both the 4096-nibble long key and the 512-nibble short key as seed material;
- a SHAKE256-based keystream bound to password, keys and length;
- a key space far beyond exhaustive search.
It is a **weaker member of a strong family**, not a broken cipher. But it is the
member to choose when you value throughput over margin, and it should not be the
default for anything that matters.
### 9.5 Recommendation
| If you are… | Use |
|---|---|
| Encrypting anything you would be upset to lose | `fast` (default) |
| Working with existing data from before 4.2.6 | `reference` or `fast` |
| Wanting a standardised keystream primitive | `turbo` |
| Encrypting large volumes where speed dominates and the threat model is mild | `raw` |
---
## 9. Deterministic output
## 11. Information leakage
ChaosCrypt has **no IV and no salt**. Encrypting the same plaintext twice
under the same key file and the same encryption password produces **the same
ciphertext**, byte for byte.
### 10.1 Message length
Ciphertext length is proportional to plaintext length in every mode. This is
true of every encryption scheme that does not pad to a fixed block size, and it
is the standard basis for traffic-analysis defence: pad your messages if the
*fact* that you sent a 43-byte message is sensitive.
### 10.2 Padding class
In `reference`, `fast` and `turbo`, the Base64 padding count (0–3) is encoded in
the ciphertext and therefore discloses `|P| mod 3`. This is two bits, strictly
subsumed by §10.1, and reveals nothing about the key or contents. `raw` does not
carry this marker.
### 10.3 Fixed substitution tables
The tables `U`, `L`, `D` and `E` remain fixed for a given key file. If you
encrypt many messages under one key file, an attacker who recovers the tables
through chosen plaintexts (§7.3) narrows the remaining problem — though it
remains infeasible. Rotating key files limits even this.
---
## 12. Legacy artefacts
Artefacts written before the header existed carry no header, and are read
through a compatibility API rather than by relaxing the reader.
### 12.1 The wrapper, not a branch
```python
from chaoscrypt import ChaosCrypt
cc = ChaosCrypt(key_file="my.key", key_password="kf-pwd", auto_load=True)
plain = cc.decrypt_legacy(old_ciphertext, "user-pwd")
```
`decrypt_legacy` synthesises a minimal header:
```json
{"is_old":true,"old_is_key":false}
```
prefixes it to the payload unchanged, and then calls the ordinary decrypt. The
ordinary path therefore **never gains a lenient branch**: it still rejects
headerless input with `E017`, and the compatibility API is the only caller that
produces the header it needs.
### 12.2 Which algorithm reads a legacy artefact
When `is_old` is true, **every other field is ignored** — including `mode`, of
which there is none. The legacy path tries the bulk-operation implementation
first and falls back to the original character pipeline. Both implement the
original algorithm, so either can read pre-header material; the fallback costs
a second attempt only if the first fails.
| Attempt | Why |
|---|---|
| 1. `fast` | Same algorithm, quicker |
| 2. `reference` | The original pipeline, if the artefact needs it |
### 12.3 Security properties of the wrapper
- **The payload is not inspected.** It is wrapped whole; nothing is inferred
from its content.
- **The header is not a weakening.** It carries no key material and no
privileges; it only tells the reader to use the legacy path.
- **Nothing is written in legacy form.** The library only reads old artefacts;
its output always carries a full header. `wrap_legacy` produces a modern
artefact, and can be used once to migrate a key file.
- **The strict path is unchanged.** A caller that passes headerless input to
`decrypt` still gets `E017`.
### 12.4 What is not supported
- Writing artefacts without a header.
- Partially trusting a legacy artefact.
- Reading a legacy artefact through `decrypt` rather than the compatibility API.
---
## 13. Deterministic output
ChaosCrypt has **no IV and no salt**, in any mode. Encrypting the same plaintext
twice under the same key file and the same encryption password produces **the
same ciphertext**, byte for byte.
This is a deliberate consequence of the design: the system key itself is
randomly generated per key file, and the initialisation role that an IV
normally plays is filled by the randomness of `K_sys`. Different key files
produce entirely different ciphertexts, and a fresh key file is the
recommended way to obtain a fresh domain of randomness.
randomly generated per key file, and the initialisation role that an IV normally
plays is filled by the randomness of `K_sys`. Different key files produce
entirely different ciphertexts, and a fresh key file is the recommended way to
obtain a fresh domain of randomness.
The practical consequences:
- **Strength is unaffected.** Confidentiality does not depend on output
variation.
- **Replay detection is your responsibility.** If two identical ciphertexts
must be distinguishable, either use a fresh key file per session or add
your own nonce — for example a timestamp — to the plaintext before
encrypting, and strip it after decryption.
- **Replay detection is your responsibility.** If two identical ciphertexts must
be distinguishable, either use a fresh key file per session or add your own
nonce — a timestamp, for example — to the plaintext before encrypting, and
strip it after decryption.
This is a design trade-off, documented here so that it is a decision rather
than a surprise.
This is a design trade-off, documented here so that it is a decision rather than
a surprise.
---
## 10. Key derivation
## 14. Key derivation, per mode
### 12.1 `reference` and `fast`
`DeriveKey(K_user, K_short, n)` performs:
@@ -419,55 +726,86 @@ than a surprise.
The pipeline is deterministic and length-extensible, and no polynomial-time
inversion from output back to input is known. Its purpose is to ensure that a
single recovered keystream yields nothing reusable, which §6.2 exploits.
single recovered keystream yields nothing reusable, which §7.2 exploits.
**A note on work factor.** DeriveKey is not a deliberately slow KDF in the
style of PBKDF2, scrypt or Argon2, and it is not intended to be. The key file
supplies 512 nibbles of independent key material, so the derived keystream
does not rest on the entropy of the password alone. If you are choosing a
password here, choose a strong one anyway — the same advice applies to every
system that accepts a passphrase.
In `fast` the same computation is performed with C-level bulk operations. The
output is identical; only the cost differs.
### 12.2 `turbo`
The keystream is `SHAKE256(seed).digest(n)` where
```
seed = domain ‖ len(K_user) ‖ K_user ‖ len(K_short) ‖ K_short
‖ K_long ‖ len(n)
```
Binding the length ensures a keystream recovered for one message is useless for
another. Binding all three secrets ensures the stream depends on the full key
material. Separate domain tags keep the inner and outer layers independent.
### 12.3 `raw`
The keystream is `SHAKE256(seed).digest(n)` where
```
seed = domain ‖ layer ‖ len(K_user) ‖ K_user ‖ len(K_short) ‖ K_short
‖ K_long ‖ len(n)
```
The `layer` field is what keeps the two XOR layers from cancelling. Note that
neither `turbo` nor `raw` seeds from a nonce, so — like every mode — they are
deterministic (§11).
### 12.4 A note on work factor
None of these is a deliberately slow KDF in the style of PBKDF2, scrypt or
Argon2, and none is intended to be. The key file supplies 512 nibbles of
independent key material, so the keystream does not rest on the entropy of the
password alone. If you are choosing a password here, choose a strong one anyway
— the same advice applies to every system that accepts a passphrase.
---
## 11. Common misconceptions
## 15. Common misconceptions
**"Known plaintext recovers the session keystream, which can then be reused."**
Recovering `K_stream` for one message does not help with another: the
keystream depends on the message length, and it cannot be inverted to
`K_user` or `K_short`. See §6.2.
Recovering a keystream for one message does not help with another: the keystream
depends on the message length, and it cannot be inverted to `K_user` or
`K_short`. See §7.2.
**"The expansion modes are public, so the keystream is predictable."**
Knowing the algorithm is not knowing the input to it. The expansion operates
on a seed derived from `K_user` and `K_short`, both unknown. This is the same
Knowing the algorithm is not knowing the input to it. The expansion operates on
a seed derived from `K_user` and `K_short`, both unknown. This is the same
situation as AES: its round function is public, and that is not a weakness.
**"`fast` is a weaker mode."**
It is not. It performs the same arithmetic on the same values and produces the
same bytes. Only the Python-level mechanics differ, and the frozen reference
vectors are asserted against it so that this cannot quietly stop being true.
**"There is no IV, so it must be broken."**
An IV provides variation when the key is fixed. Here the system key is not a
fixed global secret but freshly generated per key file, so variation is
supplied structurally. The genuine consequence is deterministic output, which
is stated plainly in §9.
fixed global secret but freshly generated per key file, so variation is supplied
structurally. The genuine consequence is deterministic output, which is stated
plainly in §11.
**"No standard KDF means the password is the weak point."**
The password does not have to carry the full security burden: it is combined
with 512 nibbles of random key material from the key file. A weak password
still degrades the composite, as it does everywhere else.
with 512 nibbles of random key material from the key file. A weak password still
degrades the composite, as it does everywhere else.
**"Unaudited means broken."**
Unaudited means unaudited. It describes what has and has not been checked,
not what is or is not true. ChaosCrypt is offered with its analysis laid out
above so that you can evaluate it directly, and with a clear statement that
it should not be relied on where certification is required.
Unaudited means unaudited. It describes what has and has not been checked, not
what is or is not true. ChaosCrypt is offered with its analysis laid out above
so that you can evaluate it directly, and with a clear statement that it should
not be relied on where certification is required.
---
## 12. Summary
## 16. Summary
ChaosCrypt's security rests on a simple proposition: **replace algebraic
structure with randomness, and place exhaustive search beyond physical
reach.**
Properties that follow from the construction:
### Properties of the construction
- The composite key space is approximately `10^5621`.
- The construction admits no compact algebraic representation.
@@ -477,40 +815,53 @@ Properties that follow from the construction:
reusable keystream.
- Shor's algorithm does not apply; Grover's algorithm changes nothing that
matters.
- Arbitrary binary data round-trips losslessly.
- Arbitrary binary data round-trips losslessly in every mode.
- There are no third-party runtime dependencies.
Properties to be aware of:
### Properties per mode
- Deterministic output for identical inputs (§9).
- Ciphertext length and `|P| mod 3` are observable (§8).
| Mode | Speed (1 MiB) | Ciphertext | Compatibility | Strength |
|---|---:|---:|---|---|
| `reference` | 0.334 s | 5.33x | pre-2.2 ✓ | baseline |
| `fast` | 0.371 s | 5.33x | pre-2.2 ✓ | **identical to `reference`** |
| `turbo` | 0.089 s | 5.33x | own format | stronger primitive |
| `raw` | 0.036 s | 1.33x | own format | weakest of the four — §9 |
### Things to be aware of
- Deterministic output for identical inputs (§11).
- Ciphertext length, and in three modes `|P| mod 3`, are observable (§10).
- `raw` additionally discloses exact plaintext length (§10.3).
- No independent audit has been performed.
**In one sentence:** ChaosCrypt is an obfuscation cipher with a strong
construction and a deliberately narrow scope. It is well suited to protecting
your own data and to studying layered cipher design. It is not a substitute
for AES-GCM or ChaCha20-Poly1305, and it should not be deployed where an
audited, standardised primitive is required.
construction and a deliberately narrow scope; its four modes trade speed against
structural margin, and the trade-offs are documented above rather than left for
you to discover.
It is well suited to protecting your own data and to studying layered cipher
design. It is not a substitute for AES-GCM or ChaCha20-Poly1305, and it should
not be deployed where an audited, standardised primitive is required.
---
## 13. Reporting a vulnerability
## 17. Reporting a vulnerability
If you believe you have found a security issue in ChaosCrypt, please report it
privately before disclosing it publicly. Include:
- a description of the issue;
- steps to reproduce, ideally with a minimal example;
- the version affected;
- the version and mode affected;
- any suggested remediation.
Reports are welcome and will be acknowledged. Note that ChaosCrypt is
maintained on a best-effort basis and comes with no warranty or support
commitment, as set out in the MIT licence.
Reports are welcome and will be acknowledged. Note that ChaosCrypt is maintained
on a best-effort basis and comes with no warranty or support commitment, as set
out in the MIT licence.
---
## 14. Licence
## 18. Licence
MIT. Provided as-is, without warranty of any kind. The authors accept no
liability for any loss or damage arising from use of this software. See
+404
View File
@@ -0,0 +1,404 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
ChaosCrypt benchmark suite
==========================
Measures the throughput of every public operation in ChaosCrypt.
Run it from the repository root so the package is importable:
python bench/benchmark.py
python bench/benchmark.py --budget 0.05 --repeats 3
python bench/benchmark.py --sizes 64,1024,65536
python bench/benchmark.py --groups Text,Binary
Why this design
---------------
* Every operation is dispatched to a process pool with one worker per CPU
core, so the whole suite completes in a single parallel wave.
* Windows uses the ``spawn`` start method, which means **lambdas and closures
cannot be pickled** and therefore cannot be sent to a worker. Every
benchmark is expressed as a *spec*: a plain, picklable dict describing the
operation and its parameters. Each worker rebuilds the callable locally.
* Inside a worker each task is warmed up, the loop count is auto-calibrated to
fill a small time budget, and the reported figure is the best of N repeats.
That way both fast operations (microseconds) and slow ones (hundreds of
milliseconds) are measured meaningfully.
What is measured
----------------
ChaosCrypt has two distinct costs, and they are reported separately:
* **Key setup** — generating key material, and loading a key file. Dominated by
``os.urandom`` calls for the former and by a 4096-nibble XOR for the latter.
* **Per-message work** — the actual encrypt/decrypt pipelines, which are
linear in message length: Base64, substitution, case flipping, reversal and
two XOR passes.
Output is a set of tables grouped by category, sorted by speed within each
group, plus a summary of wall clock, failures and memory footprint.
See ``docs/benchmark.md`` for the published results and the discussion.
"""
import argparse
import os
import sys
import time
from concurrent.futures import ProcessPoolExecutor, as_completed
# ---------------------------------------------------------------- defaults
DEFAULT_BUDGET = 0.03 # seconds of measurement per task
DEFAULT_REPEATS = 1 # best of N
KB = 1024
MB = 1024 * 1024
GROUPS = ["KeySetup", "Text", "Binary", "File", "Error", "Overhead"]
# =================================================================== timing
def _timeit(call, budget):
"""Warm up, auto-calibrate, and return (seconds_per_op, iterations)."""
call() # warm-up
n = 1
while True:
t0 = time.perf_counter()
for _ in range(n):
call()
dt = time.perf_counter() - t0
if dt >= budget or n >= (1 << 22):
break
n = max(n * 2, int(n * budget / max(dt, 1e-9)))
t0 = time.perf_counter()
for _ in range(n):
call()
return (time.perf_counter() - t0) / n, n
def _payload(size):
"""Deterministic payload, identical in every worker (no RNG involved)."""
seed = b"ChaosCrypt-benchmark-payload-"
return (seed * (size // len(seed) + 2))[:size]
def run_spec(args):
"""Executed inside a worker process. ``args`` = (spec, budget, repeats)."""
spec, budget, repeats = args
sys.path.insert(0, spec["root"])
try:
call, unit_bytes, unit_ops = _build(spec)
best = float("inf")
iters = 0
for _ in range(max(1, repeats)):
sec, n = _timeit(call, budget)
best = min(best, sec)
iters = n
except Exception as e: # noqa: BLE001
return {"name": spec["name"], "group": spec["group"],
"error": f"{type(e).__name__}: {e}"}
res = {"name": spec["name"], "group": spec["group"],
"sec_per_op": best, "ops_per_sec": unit_ops / best, "iters": iters}
if unit_bytes:
res["mb_per_sec"] = (unit_bytes * unit_ops) / best / MB
return res
# =================================================================== builders
def _fixed_core():
"""A ChaosCryptCore with deterministic key material, rebuilt per worker.
Using fixed material keeps measurements comparable between runs, and the
determinism means a warm-up cannot accidentally leave stale state.
"""
import hashlib
from chaoscrypt._core import ChaosCryptCore
def det_hex(n, seed):
out = []
h = hashlib.sha256(seed.encode()).digest()
while len(out) * 64 < n:
h = hashlib.sha256(h).digest()
out.append(h.hex())
return "".join(out)[:n]
c = ChaosCryptCore()
c.upper_mapping = "BCDEFGHIJKLMNOPQRSTUVWXYZA"
c.lower_mapping = "bcdefghijklmnopqrstuvwxyza"
c.digit_mapping = {str(i): ch for i, ch in enumerate("ABCDEFGHIJ")}
c.equal_mapping = {"0": "W", "1": "X", "2": "Z", "3": "Y"}
c.flip_pattern = [1, 0, 1, 0, 0, 1, 0, 0, 1, 0]
c.long_key = det_hex(4096, "bench-long")
c.short_key = det_hex(512, "bench-short")
c.digit_reverse = {v: k for k, v in c.digit_mapping.items()}
c.equal_reverse = {v: k for k, v in c.equal_mapping.items()}
c._build_maps()
c.keys_loaded = True
return c
def _rotating_core():
"""A core that regenerates key material on every call (key-setup cost)."""
from chaoscrypt._core import ChaosCryptCore
core = ChaosCryptCore()
def go():
core.generate_keymaterial()
return go
def _keystream(core, password, length):
"""Pre-derive the password keystream so its cost is excluded from XOR loops."""
return core._derive_final_key(password, length)
def _build(spec):
"""Map a spec to (callable, unit_bytes, unit_ops)."""
op = spec["op"]
sz = spec.get("size", 0)
pwd = spec.get("password", "benchmark-password")
# ---- key setup ----------------------------------------------------
if op == "generate_keymaterial":
return _rotating_core(), None, 1
if op == "load_keys_from_text":
import tempfile
from chaoscrypt import ChaosCrypt
tmp = tempfile.mkdtemp()
path = os.path.join(tmp, "bench.key")
src = ChaosCrypt()
src.create_key(pwd, path)
with open(path, "r") as f:
text = f.read()
from chaoscrypt._core import ChaosCryptCore
fresh = ChaosCryptCore()
return (lambda: fresh.load_keys_from_text(text, pwd)), None, 1
core = _fixed_core()
# ---- text ---------------------------------------------------------
if op == "encrypt_text":
pt = _payload(sz).decode("ascii", "ignore")
return (lambda: core.encrypt_text(pt, pwd)), sz, 1
if op == "decrypt_text":
pt = _payload(sz).decode("ascii", "ignore")
ct = core.encrypt_text(pt, pwd)
return (lambda: core.decrypt_text(ct, pwd)), sz, 1
# ---- binary -------------------------------------------------------
if op == "encrypt_bytes":
data = _payload(sz)
return (lambda: core.encrypt_bytes(data, pwd)), sz, 1
if op == "decrypt_bytes":
data = _payload(sz)
ct = core.encrypt_bytes(data, pwd)
return (lambda: core.decrypt_bytes(ct, pwd)), sz, 1
# ---- internal stages, to show where the time actually goes ---------
if op == "stage_b64encode":
import base64
data = _payload(sz)
return (lambda: base64.b64encode(data)), sz, 1
if op == "stage_substitute":
text = _payload(sz).decode("ascii", "ignore")
return (lambda: core._substitute_letters(text, core.encrypt_map)), sz, 1
if op == "stage_flip":
text = _payload(sz).decode("ascii", "ignore")
return (lambda: core._apply_flip(text)), sz, 1
if op == "stage_xor_long":
text = _payload(sz).decode("ascii", "ignore")
key = core._get_dynamic_key(len(text))
return (lambda: core._xor_encrypt_with_key(text, key)), sz, 1
if op == "stage_derive_key":
return (lambda: core._derive_final_key(pwd, sz)), None, 1
# ---- key file handling --------------------------------------------
if op == "keyfile_encrypt":
blob = _payload(sz).decode("ascii", "ignore")
return (lambda: core._xor_encrypt_data(blob, pwd)), sz, 1
if op == "keyfile_obfuscate":
keys = {
"upper_mapping": core.upper_mapping,
"lower_mapping": core.lower_mapping,
"digit_mapping": core.digit_mapping,
"equal_mapping": core.equal_mapping,
"flip_pattern": core.flip_pattern,
"long_key": core.long_key,
"short_key": core.short_key,
}
return (lambda: core._obfuscate_keys(keys)), None, 1
# ---- overhead -----------------------------------------------------
if op == "random_4096_hex":
return (lambda: core._generate_long_key(4096)), None, 1
if op == "random_512_hex":
return (lambda: core._generate_short_key(512)), None, 1
if op == "shuffle_52":
return (lambda: (core._generate_random_alphabet(),
core._generate_random_alphabet(True))), None, 1
raise ValueError("unknown op: " + op)
# =================================================================== spec table
def make_specs(sizes, groups=None, root="."):
"""Build the task list. ``sizes`` is a list of (label, byte-size)."""
S = []
a = S.append
def add(op, name, group, size=0, extra=None):
spec = {"op": op, "name": name, "group": group, "size": size, "root": root}
if extra:
spec.update(extra)
a(spec)
# Key setup
add("generate_keymaterial", "generate_keymaterial()", "KeySetup")
add("load_keys_from_text", "load_keys_from_text()", "KeySetup")
add("keyfile_obfuscate", "obfuscate_keys()", "KeySetup")
add("keyfile_encrypt", "keyfile XOR wrap [1KB]", "KeySetup", KB)
for label, size in sizes:
add("random_4096_hex", "long key 4096 nibbles", "KeySetup")
break
add("random_512_hex", "short key 512 nibbles", "KeySetup")
add("shuffle_52", "alphabet shuffles (2x)", "KeySetup")
# Text
for label, size in sizes:
add("encrypt_text", f"encrypt_text [{label}]", "Text", size)
add("decrypt_text", f"decrypt_text [{label}]", "Text", size)
# Binary
for label, size in sizes:
add("encrypt_bytes", f"encrypt_bytes [{label}]", "Binary", size)
add("decrypt_bytes", f"decrypt_bytes [{label}]", "Binary", size)
# Internal stages (1 KiB only: they are per-byte costs)
add("stage_b64encode", "stage: Base64 encode [1KB]", "Overhead", KB)
add("stage_substitute", "stage: substitution [1KB]", "Overhead", KB)
add("stage_flip", "stage: case flip [1KB]", "Overhead", KB)
add("stage_xor_long", "stage: XOR long key [1KB]", "Overhead", KB)
add("stage_derive_key", "stage: derive keystream [1KB]", "Overhead", KB)
if groups:
want = {g.lower() for g in groups}
S = [s for s in S if s["group"].lower() in want]
return S
# =================================================================== reporting
def report(results, wall, cores, mem_note=None):
ok = [r for r in results if "error" not in r]
bad = [r for r in results if "error" in r]
groups = {}
for r in ok:
groups.setdefault(r["group"], []).append(r)
for g in GROUPS:
rows = groups.get(g)
if not rows:
continue
rows.sort(key=lambda r: r["sec_per_op"])
print("=" * 96)
print(f" {g}")
print("=" * 96)
print(f" {'operation':42s} {'ops/sec':>15s} {'us/op':>10s} "
f"{'MB/s':>10s} {'iters':>10s}")
print(" " + "-" * 92)
for r in rows:
mbs = f"{r['mb_per_sec']:10.2f}" if "mb_per_sec" in r else f"{'-':>10s}"
print(f" {r['name']:42s} {r['ops_per_sec']:15,.0f} "
f"{r['sec_per_op'] * 1e6:10.3f} {mbs} {r['iters']:10,d}")
print()
if bad:
print("=" * 96)
print(" FAILED")
print("=" * 96)
for r in bad:
print(f" {r['name']:42s} {r['error']}")
print()
print("=" * 96)
print(f" {len(ok)} OK | {len(bad)} failed | wall clock {wall:.2f}s | {cores} cores")
if mem_note:
print(f" {mem_note}")
print("=" * 96)
# =================================================================== main
def main(argv=None):
ap = argparse.ArgumentParser(
description="ChaosCrypt benchmark suite (multiprocess)",
formatter_class=argparse.ArgumentDefaultsHelpFormatter,
)
ap.add_argument("--budget", type=float, default=DEFAULT_BUDGET,
help="seconds of measurement per task")
ap.add_argument("--repeats", type=int, default=DEFAULT_REPEATS,
help="take the best of N measurement rounds")
ap.add_argument("--sizes", default="64,1024",
help="comma-separated payload sizes in bytes")
ap.add_argument("--workers", type=int, default=0,
help="worker processes (0 = one per CPU core)")
ap.add_argument("--groups", default="",
help="comma-separated category filter, e.g. 'Text,Binary'")
args = ap.parse_args(argv)
root = os.getcwd()
sizes = []
for s in args.sizes.split(","):
s = s.strip()
if not s:
continue
n = int(s)
label = f"{n}B" if n < KB else (f"{n // KB}KB" if n < MB else f"{n // MB}MB")
sizes.append((label, n))
if not sizes:
ap.error("no valid --sizes given")
groups = [g.strip() for g in args.groups.split(",") if g.strip()]
specs = make_specs(sizes, groups or None, root=root)
if not specs:
ap.error("no benchmarks selected for the given --groups / --sizes")
cores = os.cpu_count() or 4
workers = args.workers or min(cores, len(specs))
print(f"[*] ChaosCrypt benchmark: {len(specs)} tasks / {workers} workers "
f"({cores} cores)", flush=True)
print(f"[*] budget {args.budget}s x {args.repeats} repeats, "
f"sizes {[l for l, _ in sizes]}"
+ (f", groups {groups}" if groups else "") + "\n", flush=True)
t0 = time.perf_counter()
results = []
with ProcessPoolExecutor(max_workers=workers) as ex:
futs = [ex.submit(run_spec, (s, args.budget, args.repeats)) for s in specs]
for i, f in enumerate(as_completed(futs), 1):
results.append(f.result())
print(f"\r {i}/{len(specs)}", end="", flush=True)
wall = time.perf_counter() - t0
print(f"\n[*] wall clock: {wall:.2f}s\n")
note = None
try:
import resource # POSIX only
ru = resource.getrusage(resource.RUSAGE_SELF).ru_maxrss
note = f"peak RSS {ru / 1024:.1f} MB"
except Exception:
pass
report(results, wall, cores, note)
return 0
if __name__ == "__main__":
sys.exit(main())
+85 -5
View File
@@ -45,7 +45,24 @@ from __future__ import annotations
import os
from typing import Optional
from ._core import ChaosCryptCore, KEYFILE_VERSION
from ._core import (
ChaosCryptCore,
KEYFILE_VERSION,
ENCODINGS,
ENC_HEX,
ENC_BASE64,
DEFAULT_ENCODING,
MIDS,
MID_BYTES,
MID_HEX,
DEFAULT_MID,
MODE_REFERENCE,
MODE_FAST,
MODE_TURBO,
MODE_RAW,
MODES,
DEFAULT_MODE,
)
from .errors import (
ChaosCryptError,
ChaosCrypt_ERR_KeyFileNotFound_E001,
@@ -66,7 +83,7 @@ from .errors import (
ChaosCrypt_ERR_UnsupportedKeyVersion_E016,
)
__version__ = "2.1.6"
__version__ = "4.2.6"
__author__ = "Dvs (DvsXT)"
__license__ = "MIT"
__all__ = [
@@ -75,6 +92,20 @@ __all__ = [
"__license__",
"DEFAULT_KEY_FILE",
"KEYFILE_VERSION",
"MODE_REFERENCE",
"MODE_FAST",
"MODE_TURBO",
"MODE_RAW",
"MODES",
"ENCODINGS",
"ENC_HEX",
"ENC_BASE64",
"DEFAULT_ENCODING",
"MIDS",
"MID_BYTES",
"MID_HEX",
"DEFAULT_MID",
"DEFAULT_MODE",
"ChaosCryptCore",
"ChaosCrypt",
"ChaosCryptError",
@@ -126,8 +157,11 @@ class ChaosCrypt:
*,
auto_load: bool = False,
default_key_file: str = DEFAULT_KEY_FILE,
mode: str = DEFAULT_MODE,
encoding: str = DEFAULT_ENCODING,
mid: str = DEFAULT_MID,
) -> None:
self.core = ChaosCryptCore()
self.core = ChaosCryptCore(mode, encoding=encoding, mid=mid)
self.key_file = key_file
self.key_password = key_password
self.default_key_file = default_key_file
@@ -269,8 +303,12 @@ class ChaosCrypt:
keys_data = self.core.generate_keymaterial()
obfuscated = self.core._obfuscate_keys(keys_data)
text = self.core._xor_encrypt_data(obfuscated, key_password)
# The returned text is exactly what would have been written to a key
# file, so it carries the header too.
document = self.core._emit(text, "key")
self.key_password = key_password
return text
return document
def info(self) -> dict:
"""Return a summary of the loaded key material.
@@ -336,12 +374,54 @@ class ChaosCrypt:
}
obfuscated = self.core._obfuscate_keys(keys_data)
encrypted = self.core._xor_encrypt_data(obfuscated, new_password)
# Every artefact carries a header, key files included. Writing the bare
# payload here would produce a file this library then refuses to load.
document = self.core._emit(encrypted, "key")
with open(target, 'w') as f:
f.write(encrypted)
f.write(document)
self.key_password = new_password
return target
# ==================================================================
# Performance settings
# ==================================================================
@property
def mode(self) -> str:
"""The active performance mode."""
return self.core.mode
@property
def encoding(self) -> str:
"""The active output encoding (used by turbo and raw)."""
return self.core.encoding
@property
def mid(self) -> str:
"""The active intermediate representation (used by turbo and raw)."""
return self.core.mid
def set_mid(self, mid: str) -> "ChaosCrypt":
"""Change the intermediate representation in place.
Only affects ``turbo`` and ``raw``; ``reference`` and ``fast`` are
character pipelines and always report ``hex``.
"""
self.core.mid = mid
return self
def set_encoding(self, encoding: str) -> "ChaosCrypt":
"""Change the output encoding in place.
Only affects ``turbo`` and ``raw``; ``reference`` and ``fast`` always
emit hex. Output decoded with the wrong encoding will fail rather than
silently produce garbage, so a ciphertext and its encoding must be kept
together.
"""
self.core.encoding = encoding
return self
# ==================================================================
# Encryption / decryption
# ==================================================================
+1366 -207
View File
File diff suppressed because it is too large Load Diff
+348
View File
@@ -0,0 +1,348 @@
"""
ChaosCrypt self-describing header.
Every key file and every ciphertext produced by this system begins with a
header that states exactly how the payload was produced. Nothing is inferred
from context, and nothing is accepted without a header.
Layout
------
b"69CES" magic bytes (hex 3639434553)
<BEGIN_MARKER> fixed hex marker (64 bytes)
{"kind": ..., ...} UTF-8 JSON configuration
<END_MARKER> fixed hex marker (64 bytes)
<payload> the key material or the ciphertext
The configuration JSON is complete on its own: it records the kind of payload,
the performance mode, whether the intermediate representation was bytes or hex,
the output encoding, the algorithm version, and the parameters needed to
reproduce the decryption path. A payload whose header is missing, truncated or
self-inconsistent is rejected rather than guessed at.
Rationale
---------
Earlier releases relied on the caller to remember which mode and encoding had
been used. That is a silent-corruption hazard: a ciphertext decrypted with the
wrong mode produces garbage that is indistinguishable from a wrong password.
Recording the parameters next to the ciphertext removes the ambiguity, and
rejecting headerless input removes the guesswork.
"""
from __future__ import annotations
import json
from typing import Any, Dict, Optional
from .errors import (
ChaosCrypt_ERR_MissingMagicHeader_E017,
ChaosCrypt_ERR_MalformedHeader_E018,
)
__all__ = [
"ENCODING_TO_OUT",
"OUT_TO_ENCODING",
"DEFAULT_MID",
"FIELD_IS_OLD",
"FIELD_OLD_IS_KEY",
"build_legacy_header",
"is_legacy",
"MAGIC",
"MAGIC_HEX",
"MAGIC_LIST",
"BEGIN_MARKER",
"END_MARKER",
"HEADER_VERSION",
"build_header",
"read_header",
"strip_header",
"has_magic",
]
# ---------------------------------------------------------------------------
# Fixed values
# ---------------------------------------------------------------------------
#: Magic bytes at the very start of every ChaosCrypt artefact.
MAGIC = b"69CES"
#: The same magic as hex text and as a list of byte values, for callers that
#: find one of those representations more convenient.
MAGIC_HEX = "3639434553"
MAGIC_LIST = [54, 57, 67, 69, 83]
#: Marker that opens the configuration block. Fixed, recorded verbatim.
BEGIN_MARKER = (
"385aeff1f4179a744c8fb0c5ae4702d325f6230d059f4251135c2536409dee93"
)
#: Marker that closes the configuration block.
END_MARKER = (
"2025ea4e4b4b93803f2ccadeaf318d1957ce42ff5409410f660348be96a4c0f2"
)
#: Version of the header format itself, independent of the algorithm version.
HEADER_VERSION = 1
#: Values accepted for the ``kind`` field.
KIND_CIPHERTEXT = "ciphertext"
KIND_KEY = "key"
KINDS = (KIND_CIPHERTEXT, KIND_KEY)
#: Values accepted for the ``mid`` (intermediate representation) field.
MID_BYTES = "bt"
MID_HEX = "hex"
MIDS = (MID_BYTES, MID_HEX)
#: Default intermediate representation for the byte-pipeline modes.
DEFAULT_MID = MID_BYTES
#: Values accepted for the ``out`` (output encoding) field.
OUT_HEX = "hex"
OUT_BASE = "base"
OUTS = (OUT_HEX, OUT_BASE)
#: Mapping from the constructor's encoding names to the header's vocabulary.
#: The constructor accepts ENC_HEX/ENC_BASE64; the header records OUT_HEX/OUT_BASE.
ENCODING_TO_OUT = {
"hex": OUT_HEX,
"base64": OUT_BASE,
}
#: And the reverse, for reading a header back into a constructor value.
OUT_TO_ENCODING = {v: k for k, v in ENCODING_TO_OUT.items()}
#: Required fields in every configuration block. Missing any one of these makes
#: the header invalid; the header is never partially trusted.
#: Field marking an artefact as produced by the pre-header implementation.
#: When present and true, **every other configuration field is ignored**; the
#: artefact is decrypted by the legacy path (see ``_core``). It is optional: a
#: normal artefact does not carry it at all.
FIELD_IS_OLD = "is_old"
#: Field naming what a legacy artefact is: true for a key file, false for a
#: ciphertext. Only meaningful alongside ``is_old``. Optional.
FIELD_OLD_IS_KEY = "old_is_key"
REQUIRED_FIELDS = (
"kind",
"v",
"mode",
"mid",
"out",
"alg",
"kdf",
"keybits",
"ksum",
)
# ---------------------------------------------------------------------------
# Building
# ---------------------------------------------------------------------------
def build_header(config: Dict[str, Any]) -> str:
"""Render a full header for ``config``.
Args:
config: The configuration dictionary. It must contain every name in
:data:`REQUIRED_FIELDS`.
Returns:
The header as text, ready to be prefixed to a payload.
Raises:
ChaosCrypt_ERR_MalformedHeader_E018: a required field is absent, or a
field holds a value outside its permitted set.
"""
# Legacy records carry only is_old and old_is_key; the strict field checks
# below do not apply to them.
legacy = bool(config.get(FIELD_IS_OLD))
if not legacy:
missing = [f for f in REQUIRED_FIELDS if f not in config]
if missing:
raise ChaosCrypt_ERR_MalformedHeader_E018(
detail="MissingConfigFields:" + ",".join(missing), code="E018"
)
if legacy:
body = json.dumps(config, ensure_ascii=False, sort_keys=True,
separators=(",", ":"))
return (MAGIC.decode("ascii") + BEGIN_MARKER + body + END_MARKER)
if config["kind"] not in KINDS:
raise ChaosCrypt_ERR_MalformedHeader_E018(
detail="BadKind:" + str(config["kind"]), code="E018"
)
if config["mid"] not in MIDS:
raise ChaosCrypt_ERR_MalformedHeader_E018(
detail="BadMid:" + str(config["mid"]), code="E018"
)
if config["out"] not in OUTS:
raise ChaosCrypt_ERR_MalformedHeader_E018(
detail="BadOut:" + str(config["out"]), code="E018"
)
# Deterministic key order so identical configurations render identically.
body = json.dumps(config, ensure_ascii=False, sort_keys=True,
separators=(",", ":"))
return (
MAGIC.decode("ascii")
+ BEGIN_MARKER
+ body
+ END_MARKER
)
def build_legacy_header(is_key: bool = False) -> str:
"""Render the minimal header used to wrap a pre-header artefact.
A legacy artefact has no header of its own, so one is synthesised before it
enters the normal decryption path. The synthesised header carries only the
two fields that matter -- ``is_old`` and ``old_is_key`` -- because once
``is_old`` is true every other field is ignored.
This keeps a single code path: the library always decrypts something that
has a header. Legacy support is a wrapper around that path, not a second
implementation of it.
Args:
is_key: Whether the artefact is a key file rather than a ciphertext.
Returns:
A complete header, ready to be prefixed to a legacy payload.
"""
body = json.dumps(
{FIELD_IS_OLD: True, FIELD_OLD_IS_KEY: bool(is_key)},
ensure_ascii=False, sort_keys=True, separators=(",", ":"),
)
return MAGIC.decode("ascii") + BEGIN_MARKER + body + END_MARKER
def is_legacy(text: str) -> bool:
"""Whether ``text`` is a headed legacy artefact.
Returns ``False`` for anything that is not a parseable header, so callers
can use this as a test rather than a validator.
"""
try:
cfg = read_header(text)
except Exception:
return False
return bool(cfg.get(FIELD_IS_OLD))
# ---------------------------------------------------------------------------
# Parsing
# ---------------------------------------------------------------------------
def has_magic(text: str) -> bool:
"""Whether ``text`` begins with the ChaosCrypt magic bytes."""
return text.startswith(MAGIC.decode("ascii"))
def read_header(text: str) -> Dict[str, Any]:
"""Parse the header from ``text`` and return its configuration.
Raises:
ChaosCrypt_ERR_MissingMagicHeader_E017: ``text`` does not start with the
magic. Callers must not attempt to guess the format.
ChaosCrypt_ERR_MalformedHeader_E018: a marker is missing or the JSON is
invalid or incomplete.
"""
if not text:
raise ChaosCrypt_ERR_MissingMagicHeader_E017(
detail="EmptyInput", code="E017"
)
magic = MAGIC.decode("ascii")
if not text.startswith(magic):
raise ChaosCrypt_ERR_MissingMagicHeader_E017()
body_at = len(magic)
if not text.startswith(BEGIN_MARKER, body_at):
raise ChaosCrypt_ERR_MalformedHeader_E018(
detail="MissingBeginMarker", code="E018"
)
body_at += len(BEGIN_MARKER)
end_at = text.find(END_MARKER, body_at)
if end_at < 0:
raise ChaosCrypt_ERR_MalformedHeader_E018(
detail="MissingEndMarker", code="E018"
)
body = text[body_at:end_at]
try:
config = json.loads(body)
except Exception:
raise ChaosCrypt_ERR_MalformedHeader_E018(
detail="InvalidHeaderJson", code="E018"
)
if not isinstance(config, dict):
raise ChaosCrypt_ERR_MalformedHeader_E018(
detail="HeaderJsonNotObject", code="E018"
)
# A legacy artefact carries only is_old and old_is_key. Everything else is
# meaningless for it, so the required-field check is skipped entirely --
# requiring kind/mode/... here would reject the very artefacts this branch
# exists to read.
if config.get(FIELD_IS_OLD):
if FIELD_OLD_IS_KEY in config and not isinstance(
config[FIELD_OLD_IS_KEY], bool
):
raise ChaosCrypt_ERR_MalformedHeader_E018(
detail="OldIsKeyNotBoolean", code="E018"
)
return config
missing = [f for f in REQUIRED_FIELDS if f not in config]
if missing:
raise ChaosCrypt_ERR_MalformedHeader_E018(
detail="MissingConfigFields:" + ",".join(missing), code="E018"
)
return config
def _payload_offset(text: str) -> int:
"""Index at which the payload begins, or ``-1`` if the header is unusable.
Markers are located by index so no intermediate copy of the payload is
made. The payload can be tens of megabytes; slicing the whole string three
times, as an earlier version did, costs three full copies per call and shows
up directly in throughput.
"""
magic = MAGIC.decode("ascii")
if not text.startswith(magic):
return -1
body_at = len(magic)
if not text.startswith(BEGIN_MARKER, body_at):
return -1
body_at += len(BEGIN_MARKER)
end_at = text.find(END_MARKER, body_at)
if end_at < 0:
return -1
return end_at + len(END_MARKER)
def strip_header(text: str) -> str:
"""Return the payload that follows the header.
The header is validated on the way through, so a malformed header raises
rather than yielding a payload.
Raises:
ChaosCrypt_ERR_MissingMagicHeader_E017: no magic present.
ChaosCrypt_ERR_MalformedHeader_E018: header could not be parsed.
"""
if not has_magic(text):
raise ChaosCrypt_ERR_MissingMagicHeader_E017()
read_header(text) # validate the record itself
offset = _payload_offset(text)
if offset < 0:
raise ChaosCrypt_ERR_MalformedHeader_E018(
detail="MissingEndMarker", code="E018"
)
return text[offset:] # a single slice
+55 -6
View File
@@ -22,7 +22,8 @@ import os
import sys
from typing import List, Optional
from . import DEFAULT_KEY_FILE, __version__
from . import (DEFAULT_KEY_FILE, __version__, MODES, DEFAULT_MODE,
ENCODINGS, DEFAULT_ENCODING, MIDS, DEFAULT_MID)
from .errors import ChaosCryptError, ChaosCrypt_ERR_InvalidArgument_E013
__all__ = ["build_parser", "main", "cli_main"]
@@ -102,6 +103,18 @@ def _add_global_flags(parser: argparse.ArgumentParser) -> None:
dest="quiet_local",
help="suppress non-essential human-readable output",
)
parser.add_argument(
"--mode", choices=MODES, default=None, dest="mode_local", metavar="MODE",
help="performance mode: reference / fast / turbo / raw",
)
parser.add_argument(
"--encoding", choices=ENCODINGS, default=None, dest="encoding_local",
metavar="ENC", help="output encoding for turbo/raw: hex / base64",
)
parser.add_argument(
"--mid", choices=MIDS, default=None, dest="mid_local", metavar="MID",
help="intermediate representation for turbo/raw: bt / hex",
)
def _add_password_opts(
@@ -179,6 +192,33 @@ def build_parser() -> argparse.ArgumentParser:
"-q", "--quiet", action="store_true",
help="suppress non-essential human-readable output",
)
parser.add_argument(
"--mid", choices=MIDS, default=None, metavar="MID",
help=(
"intermediate representation for turbo/raw: 'bt' (bytes, default, "
"2.00x expansion) or 'hex' (hexadecimal text, ~4x). Ignored by "
"reference/fast."
),
)
parser.add_argument(
"--encoding", choices=ENCODINGS, default=None, metavar="ENC",
help=(
"output encoding for turbo/raw: 'hex' (2.00x expansion) or "
"'base64' (1.33x). Ignored by reference/fast, which always emit "
f"hex. Default: {DEFAULT_ENCODING}"
),
)
parser.add_argument(
"--mode", choices=MODES, default=None, metavar="MODE",
help=(
"performance mode. "
"'reference' is the original algorithm (slowest, baseline); "
"'fast' is bit-for-bit identical to it but uses C-level bulk "
"operations; 'turbo' derives the keystream with SHAKE256 and is "
"far faster, but its ciphertexts are not interchangeable with the "
f"other two. Default: {DEFAULT_MODE}"
),
)
sub = parser.add_subparsers(dest="command", metavar="<command>")
@@ -400,7 +440,7 @@ def _cmd_keygen(args: argparse.Namespace) -> int:
args,
)
cc = ChaosCrypt()
cc = ChaosCrypt(mode=args.mode, encoding=args.encoding, mid=args.mid)
path = cc.create_key(pwd, args.key_file, overwrite=args.force)
_emit(
{"ok": True, "key_file": os.path.abspath(path)},
@@ -434,7 +474,7 @@ def _cmd_text(args: argparse.Namespace, mode: str) -> int:
args.text, args.in_file, "plaintext" if mode == "encrypt" else "ciphertext"
)
cc = ChaosCrypt()
cc = ChaosCrypt(mode=args.mode, encoding=args.encoding, mid=args.mid)
cc.load(args.key_file, key_pwd)
if mode == "encrypt":
@@ -483,7 +523,7 @@ def _cmd_file(args: argparse.Namespace, mode: str) -> int:
args,
)
cc = ChaosCrypt()
cc = ChaosCrypt(mode=args.mode, encoding=args.encoding, mid=args.mid)
cc.load(args.key_file, key_pwd)
if mode == "encrypt":
@@ -520,7 +560,7 @@ def _cmd_info(args: argparse.Namespace) -> int:
args,
)
cc = ChaosCrypt()
cc = ChaosCrypt(mode=args.mode, encoding=args.encoding, mid=args.mid)
cc.load(args.key_file, key_pwd)
info = cc.info()
@@ -560,7 +600,7 @@ def _cmd_chpwd(args: argparse.Namespace) -> int:
args,
)
cc = ChaosCrypt()
cc = ChaosCrypt(mode=args.mode, encoding=args.encoding, mid=args.mid)
path = cc.change_key_password(old, new, args.key_file)
_emit(
{"ok": True, "key_file": os.path.abspath(path)},
@@ -596,6 +636,15 @@ def main(argv: Optional[List[str]] = None) -> int:
or getattr(args, "json_local", False))
args.quiet = bool(getattr(args, "quiet", False)
or getattr(args, "quiet_local", False))
args.mode = (getattr(args, "mode", None)
or getattr(args, "mode_local", None)
or DEFAULT_MODE)
args.encoding = (getattr(args, "encoding", None)
or getattr(args, "encoding_local", None)
or DEFAULT_ENCODING)
args.mid = (getattr(args, "mid", None)
or getattr(args, "mid_local", None)
or DEFAULT_MID)
if args.command is None or args.command == "tui":
from .tui import run_tui
+14
View File
@@ -34,6 +34,8 @@ __all__ = [
"ChaosCrypt_ERR_FileReadFailed_E014",
"ChaosCrypt_ERR_FileWriteFailed_E015",
"ChaosCrypt_ERR_UnsupportedKeyVersion_E016",
"ChaosCrypt_ERR_MissingMagicHeader_E017",
"ChaosCrypt_ERR_MalformedHeader_E018",
]
@@ -143,3 +145,15 @@ ChaosCrypt_ERR_UnsupportedKeyVersion_E016 = _define(
"ChaosCrypt_ERR_UnsupportedKeyVersion_E016", "UnsupportedKeyVersion", "E016",
"The key file declares a format version this build cannot read.",
)
ChaosCrypt_ERR_MissingMagicHeader_E017 = _define(
"ChaosCrypt_ERR_MissingMagicHeader_E017", "MissingMagicHeader", "E017",
"The input does not begin with the ChaosCrypt magic header. Every key file "
"and ciphertext produced by this system carries a self-describing header; "
"input without one is rejected outright.",
)
ChaosCrypt_ERR_MalformedHeader_E018 = _define(
"ChaosCrypt_ERR_MalformedHeader_E018", "MalformedHeader", "E018",
"The ChaosCrypt header is present but could not be parsed: a marker is "
"missing, the JSON is invalid, or a required field is absent.",
)
+39
View File
@@ -71,6 +71,45 @@ TEXTS: Dict[str, Dict[str, str]] = {
"menu_keyinfo": {"en": "Show key information", "zh": "查看当前密钥信息"},
"menu_chpwd": {"en": "Change key file password", "zh": "修改密钥文件密码"},
"menu_lang": {"en": "Switch language", "zh": "切换语言"},
"menu_mode": {"en": "Performance mode", "zh": "性能模式"},
"menu_encoding": {"en": "Output encoding", "zh": "输出编码"},
"info_encoding": {"en": "Output encoding", "zh": "输出编码"},
"encoding_prompt": {"en": "Select output encoding", "zh": "请选择输出编码"},
"encoding_hex_desc": {
"en": "hex - 2 characters per byte, 2.00x expansion",
"zh": "hex - 每字节 2 字符,膨胀 2.00 倍",
},
"encoding_base64_desc": {
"en": "base64 - 4 characters per 3 bytes, 1.33x expansion",
"zh": "base64 - 每 3 字节 4 字符,膨胀 1.33 倍",
},
"encoding_changed": {"en": "Encoding set to", "zh": "输出编码已设为"},
"encoding_note": {
"en": "(only affects turbo and raw; reference and fast always emit hex)",
"zh": "(仅影响 turbo 与 raw;reference 与 fast 恒为 hex)",
},
"info_mode": {"en": "Performance mode", "zh": "性能模式"},
"mode_prompt": {
"en": "Select performance mode",
"zh": "请选择性能模式",
},
"mode_reference_desc": {
"en": "reference - original algorithm, slowest, ciphertext compatible",
"zh": "reference - 原版算法,最慢,密文兼容",
},
"mode_fast_desc": {
"en": "fast - identical ciphertext, C-level bulk operations",
"zh": "fast - 密文相同,C 级批量运算",
},
"mode_turbo_desc": {
"en": "turbo - SHAKE256 keystream, much faster, own ciphertext format",
"zh": "turbo - SHAKE256 密钥流,极快,独立密文格式",
},
"mode_raw_desc": {
"en": "raw - bytes throughout, fastest, smallest output, weakest",
"zh": "raw - 全程字节,最快,输出最小,强度最低",
},
"mode_changed": {"en": "Mode set to", "zh": "模式已设为"},
"menu_about": {"en": "About / security notice", "zh": "关于 / 安全声明"},
"menu_quit": {"en": "Quit", "zh": "退出"},
"menu_prompt": {"en": "Enter option", "zh": "请输入选项编号"},
View File
+31
View File
@@ -0,0 +1,31 @@
# -*- coding: utf-8 -*-
"""Test-vector loading helper.
Mirrors the loader used by the sibling ``purepycrypto`` project so the two
repositories share the same layout convention: a ``vectors/`` directory next to
the tests, one JSON file per subject, loaded by name.
"""
import json
import os
VEC_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "vectors")
def path_for(name):
"""Absolute path of ``vectors/<name>.json``."""
return os.path.join(VEC_DIR, name + ".json")
def load(name):
"""Load ``vectors/<name>.json`` and return the parsed dictionary."""
with open(path_for(name), "r", encoding="utf-8") as f:
return json.load(f)
def available():
"""Names of every vector file present, without the ``.json`` suffix."""
if not os.path.isdir(VEC_DIR):
return []
return sorted(
f[:-5] for f in os.listdir(VEC_DIR) if f.endswith(".json")
)
+92 -17
View File
@@ -73,8 +73,9 @@ class TestRoundTrip:
ct = loaded.encrypt(text, USER_PWD)
assert loaded.decrypt(ct, USER_PWD) == text
def test_ciphertext_is_hex(self, loaded):
ct = loaded.encrypt("data", USER_PWD)
def test_ciphertext_payload_is_hex(self, loaded):
from chaoscrypt._header import strip_header
ct = strip_header(loaded.encrypt("data", USER_PWD))
int(ct, 16)
def test_empty_plaintext_rejected(self, loaded):
@@ -98,21 +99,37 @@ class TestRoundTrip:
b = loaded.encrypt("same", "pwd-B")
assert a != b
def test_non_hex_ciphertext_rejected(self, loaded):
def test_every_ciphertext_carries_a_header(self, loaded):
from chaoscrypt._header import MAGIC, read_header
ct = loaded.encrypt("data", USER_PWD)
assert ct.startswith(MAGIC.decode())
cfg = read_header(ct)
assert cfg["kind"] == "ciphertext"
def test_headerless_ciphertext_rejected(self, loaded):
"""Input without the magic header is not a CES artefact."""
with pytest.raises(ChaosCryptError) as ei:
loaded.decrypt("zzzz-not-hex", USER_PWD)
assert ei.value.code == "E010"
assert ei.value.code == "E017"
def test_odd_length_ciphertext_rejected(self, loaded):
def test_headerless_odd_length_rejected(self, loaded):
with pytest.raises(ChaosCryptError) as ei:
loaded.decrypt("abc", USER_PWD)
assert ei.value.code == "E010"
assert ei.value.code == "E017"
def test_empty_ciphertext_rejected(self, loaded):
with pytest.raises(ChaosCryptError) as ei:
loaded.decrypt("", USER_PWD)
assert ei.value.code == "E009"
def test_malformed_payload_rejected(self, loaded):
"""A valid header with a broken payload fails on the payload."""
from chaoscrypt._header import build_header
bad = build_header(loaded.core.header_config("ciphertext")) + "zzzz"
with pytest.raises(ChaosCryptError) as ei:
loaded.decrypt(bad, USER_PWD)
assert ei.value.code == "E010"
# ---------------------------------------------------------------------------
# Binary
@@ -148,6 +165,33 @@ class TestKeyManagement:
n.load(path, KEY_PWD)
assert n.loaded
def test_key_file_carries_a_header(self, tmp_path):
from chaoscrypt._header import MAGIC, read_header
path = str(tmp_path / "hdr.key")
ChaosCrypt().create_key(KEY_PWD, path)
text = open(path, encoding="utf-8").read()
assert text.startswith(MAGIC.decode())
cfg = read_header(text)
assert cfg["kind"] == "key"
assert cfg["alg"] == "chaoscrypt"
def test_headerless_key_file_rejected(self, tmp_path):
path = tmp_path / "bare.key"
path.write_text("deadbeef" * 200, encoding="utf-8")
with pytest.raises(ChaosCryptError) as ei:
ChaosCrypt().load(str(path), KEY_PWD)
assert ei.value.code == "E017"
def test_key_file_rejected_as_ciphertext(self, tmp_path):
path = str(tmp_path / "k2.key")
ChaosCrypt().create_key(KEY_PWD, path)
text = open(path, encoding="utf-8").read()
cc = ChaosCrypt()
cc.load(path, KEY_PWD)
with pytest.raises(ChaosCryptError) as ei:
cc.decrypt(text, USER_PWD)
assert ei.value.code == "E018"
def test_keygen_refuses_overwrite(self, tmp_path):
path = str(tmp_path / "k.key")
ChaosCrypt().create_key(KEY_PWD, path)
@@ -179,14 +223,14 @@ class TestKeyManagement:
path.write_text("this is not a chaoscrypt key file!!!", encoding="utf-8")
with pytest.raises(ChaosCryptError) as ei:
ChaosCrypt().load(str(path), KEY_PWD)
assert ei.value.code == "E002"
assert ei.value.code == "E017"
def test_load_empty_file(self, tmp_path):
path = tmp_path / "empty.key"
path.write_text("", encoding="utf-8")
with pytest.raises(ChaosCryptError) as ei:
ChaosCrypt().load(str(path), KEY_PWD)
assert ei.value.code == "E002"
assert ei.value.code in ("E002", "E017")
def test_encrypt_without_key_raises(self):
cc = ChaosCrypt()
@@ -223,10 +267,13 @@ class TestKeyManagement:
assert len(info["flip_pattern"]) == 10
def test_export_and_import_key_text(self):
from chaoscrypt._header import MAGIC, read_header
cc = ChaosCrypt()
text = cc.export_key_text(KEY_PWD)
assert text and isinstance(text, str)
assert cc.loaded, "export_key_text should leave the instance usable"
assert text.startswith(MAGIC.decode())
assert read_header(text)["kind"] == "key"
n = ChaosCrypt()
n.load_from_text(text, KEY_PWD)
@@ -283,6 +330,13 @@ class TestFileAPI:
back = loaded.decrypt_file(cc_file, USER_PWD, dst)
assert open(back, "rb").read() == payload
def test_encrypted_file_carries_a_header(self, loaded, tmp_path):
from chaoscrypt._header import MAGIC
src = tmp_path / "h.txt"
src.write_text("header check", encoding="utf-8")
out = loaded.encrypt_file(str(src), USER_PWD)
assert open(out, encoding="utf-8").read().startswith(MAGIC.decode())
def test_default_suffixes(self, loaded, tmp_path):
src = tmp_path / "note.txt"
src.write_text("hello file", encoding="utf-8")
@@ -351,9 +405,14 @@ class TestErrorClass:
# ---------------------------------------------------------------------------
class TestLegacyCompatibility:
def test_format_matches_original_chain(self, loaded):
"""Reproduce the original decryption chain step by step."""
"""Reproduce the original decryption chain step by step.
The artefact carries a header, so the payload is taken from it first;
the chain that follows is the original one, unchanged.
"""
from chaoscrypt._header import strip_header
text = "compat check compatibility"
ct = loaded.encrypt(text, USER_PWD)
ct = strip_header(loaded.encrypt(text, USER_PWD))
core = loaded.core
combined = core._xor_decrypt_with_final_key(ct, USER_PWD)
@@ -370,11 +429,12 @@ class TestLegacyCompatibility:
assert base64.b64decode((sub + "=" * eq_count).encode()).decode() == text
def test_keyfile_readable_by_original_scheme(self, keyfile):
"""A newly generated key file must satisfy the original format."""
"""The payload of a new key file must satisfy the original format."""
from chaoscrypt._header import strip_header
_, path = keyfile
core = ChaosCryptCore()
with open(path, "r") as f:
enc = f.read()
enc = strip_header(f.read())
decrypted = core._xor_decrypt_data(enc, KEY_PWD)
assert decrypted is not None
@@ -462,9 +522,10 @@ class TestCLI:
)
def test_version(self):
from chaoscrypt import __version__
r = self._run(["--version"])
assert r.returncode == 0
assert "2.1.6" in r.stdout
assert __version__ in r.stdout
def test_help_mentions_scope(self):
r = self._run(["--help"])
@@ -574,13 +635,22 @@ class TestCLI:
assert r.stdout.strip() == "", args
def test_plain_output_is_bare_ciphertext(self, tmp_path):
"""Without --json the ciphertext goes to stdout on its own."""
"""Without --json the artefact goes to stdout on its own.
"On its own" means no JSON envelope around it. The artefact does contain
the word ``ciphertext`` inside its header's ``kind`` field, so the check
is for the envelope rather than for the word.
"""
from chaoscrypt._header import MAGIC, strip_header
kf = str(tmp_path / "p.key")
self._run(["keygen", "-k", kf, "-P", KEY_PWD])
r = self._run(["encrypt", "x", "-p", USER_PWD, "-k", kf, "-P", KEY_PWD])
out = r.stdout.strip()
assert out and "ciphertext" not in out
int(out, 16)
assert out
assert not out.startswith("{"), "unexpected JSON envelope"
assert out.startswith(MAGIC.decode())
int(strip_header(out), 16)
def test_chpwd(self, tmp_path):
kf = str(tmp_path / "c.key")
@@ -598,12 +668,17 @@ class TestCLI:
# ---------------------------------------------------------------------------
class TestCoreDirect:
def test_core_generate_and_use(self):
"""Key material moves between instances through the key file scheme."""
from chaoscrypt._header import build_legacy_header
c = ChaosCryptCore()
data = c.generate_keymaterial()
ct = c.encrypt_text("core direct", USER_PWD)
assert c.decrypt_text(ct, USER_PWD) == "core direct"
text = c._xor_encrypt_data(c._obfuscate_keys(data), KEY_PWD)
# load_keys_from_text now requires a header, as every artefact does.
# A minimal one is enough when the material is already at hand.
text = build_legacy_header(is_key=True) + \
c._xor_encrypt_data(c._obfuscate_keys(data), KEY_PWD)
c2 = ChaosCryptCore()
c2.load_keys_from_text(text, KEY_PWD)
assert c2.decrypt_text(ct, USER_PWD) == "core direct"
+25 -75
View File
@@ -1,84 +1,34 @@
# -*- coding: utf-8 -*-
"""
Bidirectional interoperability tests against the original implementation.
Legacy interoperability: deliberately removed.
These tests load ``chaoscrypt/legacy/chaoscrypt_legacy.py`` and prove that:
Until 4.2.6 the library could exchange key files and ciphertexts with the
original single-file script. That interoperability was given up when the
self-describing header was introduced: every artefact now begins with a magic
value, two fixed markers and a configuration record, and a reader rejects
anything without one.
* ciphertext produced by the original script decrypts with the packaged
library, and
* ciphertext produced by the packaged library decrypts with the original
script.
The break is intentional in both directions:
They are the regression guard for the promise that the algorithm itself was
ported without any behavioural change.
* a key file written by this version cannot be read by the original script;
* a ciphertext written by this version cannot be decrypted by the original
script;
* artefacts written before the header existed are rejected with
``E017 MissingMagicHeader``.
Reading old material is still possible through the compatibility API, which
synthesises a minimal header and then uses the ordinary path. That is covered
by ``test_header.py``; there is nothing left to assert here.
The original implementation is kept under ``legacy/`` for reference only.
"""
import importlib.util
import os
import pytest
from chaoscrypt import ChaosCrypt
KEY_PWD = "legacy-key-password"
USER_PWD = "legacy-user-password"
SAMPLES = [
"legacy compatibility",
"兼容性检查",
"x" * 300,
"emoji test 🎉",
"multi\nline\ttabbed",
]
def _load_legacy():
"""Import the legacy single-file implementation, or skip if absent."""
here = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
legacy = os.path.join(here, "legacy", "chaoscrypt_legacy.py")
if not os.path.exists(legacy):
pytest.skip("legacy implementation not present")
spec = importlib.util.spec_from_file_location("cc_legacy", legacy)
mod = importlib.util.module_from_spec(spec)
spec.loader.exec_module(mod)
return mod
class TestLegacyInterop:
def test_library_decrypts_legacy_ciphertext(self, tmp_path):
legacy_mod = _load_legacy()
kf = str(tmp_path / "legacy.key")
old = legacy_mod.EncryptionSystem()
old.generate_keys(kf, KEY_PWD)
pairs = [(tx, old.encrypt(tx, USER_PWD)) for tx in SAMPLES]
new = ChaosCrypt()
new.load(kf, KEY_PWD)
for tx, ct in pairs:
assert new.decrypt(ct, USER_PWD) == tx
def test_legacy_decrypts_library_ciphertext(self, tmp_path):
legacy_mod = _load_legacy()
kf = str(tmp_path / "legacy2.key")
new = ChaosCrypt()
new.create_key(KEY_PWD, kf)
old = legacy_mod.EncryptionSystem()
old._load_keys(kf, KEY_PWD)
for tx in SAMPLES:
ct = new.encrypt(tx, USER_PWD)
assert old.decrypt(ct, USER_PWD) == tx
def test_key_files_are_identical_in_format(self, tmp_path):
"""A library key file must load in the original implementation."""
legacy_mod = _load_legacy()
kf = str(tmp_path / "fmt.key")
ChaosCrypt().create_key(KEY_PWD, kf)
old = legacy_mod.EncryptionSystem()
old._load_keys(kf, KEY_PWD)
assert old.keys_loaded
@pytest.mark.skip(reason="interoperability with pre-4.2.6 artefacts was "
"intentionally dropped when the header was added; "
"see the compatibility API instead")
def test_legacy_interop_removed():
"""Placeholder so the removal shows up in the test report."""
assert True
+416
View File
@@ -0,0 +1,416 @@
# -*- coding: utf-8 -*-
"""
Performance-mode tests.
Four modes exist:
reference the original algorithm, character pipeline
fast same algorithm, bulk-operation implementation, identical output
turbo SHAKE256 keystream, byte pipeline, own ciphertext format
raw byte pipeline with the long-key layer retained
``reference`` and ``fast`` produce indistinguishable ciphertexts and always use
hex. ``turbo`` and ``raw`` accept either ``hex`` or ``base64`` output, and
either a ``bt`` (bytes) or ``hex`` intermediate representation.
Every artefact carries a self-describing header, so anything that inspects the
ciphertext body strips it first, and anything that feeds headerless input
expects ``E017``.
"""
import os
import pytest
from chaoscrypt import (
ChaosCrypt,
ChaosCryptCore,
ChaosCryptError,
MODES,
MODE_REFERENCE,
MODE_FAST,
MODE_TURBO,
MODE_RAW,
DEFAULT_MODE,
ENCODINGS,
ENC_HEX,
ENC_BASE64,
MIDS,
MID_BYTES,
MID_HEX,
)
from chaoscrypt._header import MAGIC, strip_header, read_header
from ._vectors import load
KEY_PWD = "mode-key-password"
USER_PWD = "mode-user-password"
SAMPLES = [
"hello",
"hello world",
"emoji test",
"a",
"x" * 300,
"Mixed 123!@#$%^&*",
"line1\nline2\ttabbed",
]
def _payload(text: str) -> str:
"""The payload of an artefact, with its self-describing header removed."""
return strip_header(text)
def _core(mode, vectors, enc="hex", mid="bt"):
"""A ChaosCryptCore in ``mode`` carrying the frozen key material."""
km = vectors["key_material"]
c = ChaosCryptCore(mode, "hash", enc, mid)
c.upper_mapping = km["upper_mapping"]
c.lower_mapping = km["lower_mapping"]
c.digit_mapping = km["digit_mapping"]
c.equal_mapping = km["equal_mapping"]
c.flip_pattern = km["flip_pattern"]
c.long_key = km["long_key"]
c.short_key = km["short_key"]
c.digit_reverse = {v: k for k, v in c.digit_mapping.items()}
c.equal_reverse = {v: k for k, v in c.equal_mapping.items()}
c._build_maps()
c.keys_loaded = True
return c
@pytest.fixture(scope="module")
def vectors():
return load("chaoscrypt_reference")
@pytest.fixture(scope="module")
def cores(vectors):
return {m: _core(m, vectors) for m in MODES}
@pytest.fixture
def keyfile(tmp_path):
path = str(tmp_path / "modes.key")
ChaosCrypt().create_key(KEY_PWD, path)
return path
# ---------------------------------------------------------------------------
# Mode surface
# ---------------------------------------------------------------------------
class TestModeSurface:
def test_all_four_modes_are_exported(self):
assert MODES == (MODE_REFERENCE, MODE_FAST, MODE_TURBO, MODE_RAW)
def test_default_mode_is_fast(self):
assert DEFAULT_MODE == MODE_FAST
def test_core_defaults_to_the_default_mode(self):
assert ChaosCryptCore().mode == DEFAULT_MODE
def test_unknown_mode_is_rejected(self):
with pytest.raises(ValueError):
ChaosCryptCore("turbo-charged")
def test_valid_mode_is_accepted(self):
for m in MODES:
assert ChaosCryptCore(m).mode == m
# ---------------------------------------------------------------------------
# reference and fast
# ---------------------------------------------------------------------------
class TestReferenceAndFast:
def test_reference_reproduces_frozen_vectors(self, cores, vectors):
core = cores[MODE_REFERENCE]
pwd = vectors["passwords"]["user_password"]
for case in vectors["cases"]:
if case.get("mode", "fast") not in ("reference", "fast"):
continue
got = _payload(core.encrypt_text(case["plaintext"], pwd))
want = _payload(case["ciphertext"])
assert got == want, f"reference drifted for {case['id']}"
def test_fast_is_indistinguishable_from_reference(self, cores, vectors):
"""The whole point of `fast`: same bytes, less time."""
pwd = vectors["passwords"]["user_password"]
for case in vectors["cases"]:
a = cores[MODE_REFERENCE].encrypt_text(case["plaintext"], pwd)
b = cores[MODE_FAST].encrypt_text(case["plaintext"], pwd)
# payloads identical; only the recorded mode differs
assert _payload(a) == _payload(b), case["id"]
assert read_header(a)["mode"] == MODE_REFERENCE
assert read_header(b)["mode"] == MODE_FAST
@pytest.mark.parametrize("text", SAMPLES)
def test_fast_matches_reference_on_samples(self, cores, text):
a = _payload(cores[MODE_REFERENCE].encrypt_text(text, USER_PWD))
b = _payload(cores[MODE_FAST].encrypt_text(text, USER_PWD))
assert a == b
def test_agree_on_large_input(self, cores):
big = "A" * 40_000
a = _payload(cores[MODE_REFERENCE].encrypt_text(big, USER_PWD))
b = _payload(cores[MODE_FAST].encrypt_text(big, USER_PWD))
assert a == b
@pytest.mark.parametrize("mode", [MODE_REFERENCE, MODE_FAST])
def test_ciphertext_payload_is_hex(self, cores, mode):
int(_payload(cores[mode].encrypt_text("data", USER_PWD)), 16)
# ---------------------------------------------------------------------------
# turbo and raw
# ---------------------------------------------------------------------------
class TestTurboAndRaw:
@pytest.mark.parametrize("mode", [MODE_TURBO, MODE_RAW])
@pytest.mark.parametrize("text", SAMPLES)
def test_roundtrip(self, cores, mode, text):
ct = cores[mode].encrypt_text(text, USER_PWD)
assert cores[mode].decrypt_text(ct, USER_PWD) == text
@pytest.mark.parametrize("mode", [MODE_TURBO, MODE_RAW])
@pytest.mark.parametrize("size", [1, 2, 255, 4096])
def test_binary_roundtrip(self, cores, mode, size):
raw = os.urandom(size)
ct = cores[mode].encrypt_bytes(raw, USER_PWD)
assert cores[mode].decrypt_bytes(ct, USER_PWD) == raw
@pytest.mark.parametrize("mode", MODES)
def test_every_ciphertext_carries_a_header(self, cores, mode):
ct = cores[mode].encrypt_text("data", USER_PWD)
assert ct.startswith(MAGIC.decode())
assert read_header(ct)["kind"] == "ciphertext"
@pytest.mark.parametrize("mode", [MODE_TURBO, MODE_RAW])
def test_wrong_password_fails(self, cores, mode):
ct = cores[mode].encrypt_text("secret", USER_PWD)
with pytest.raises(ChaosCryptError):
cores[mode].decrypt_text(ct, "wrong-password")
# ---------------------------------------------------------------------------
# Intermediates and encodings
# ---------------------------------------------------------------------------
class TestIntermediatesAndEncodings:
@pytest.mark.parametrize("mode", [MODE_TURBO, MODE_RAW])
@pytest.mark.parametrize("mid", MIDS)
@pytest.mark.parametrize("enc", ENCODINGS)
def test_all_combinations_round_trip(self, vectors, mode, mid, enc):
c = _core(mode, vectors, enc, mid)
for text in SAMPLES:
ct = c.encrypt_text(text, USER_PWD)
assert c.decrypt_text(ct, USER_PWD) == text, (mode, mid, enc)
@pytest.mark.parametrize("mode", [MODE_TURBO, MODE_RAW])
@pytest.mark.parametrize("mid", MIDS)
def test_binary_round_trip_all_mids(self, vectors, mode, mid):
c = _core(mode, vectors, "hex", mid)
raw = os.urandom(2_000)
assert c.decrypt_bytes(c.encrypt_bytes(raw, USER_PWD), USER_PWD) == raw
@pytest.mark.parametrize("mid", MIDS)
def test_header_records_the_mid(self, vectors, mid):
for mode in (MODE_TURBO, MODE_RAW):
c = _core(mode, vectors, "hex", mid)
cfg = read_header(c.encrypt_text("x", USER_PWD))
assert cfg["mid"] == mid, mode
@pytest.mark.parametrize("enc", ENCODINGS)
def test_header_records_the_encoding(self, vectors, enc):
for mode in (MODE_TURBO, MODE_RAW):
c = _core(mode, vectors, enc, "bt")
cfg = read_header(c.encrypt_text("x", USER_PWD))
want = "base" if enc == ENC_BASE64 else "hex"
assert cfg["out"] == want, mode
def test_legacy_modes_always_report_hex(self, vectors):
for mode in (MODE_REFERENCE, MODE_FAST):
c = _core(mode, vectors, ENC_BASE64, MID_HEX)
cfg = read_header(c.encrypt_text("x", USER_PWD))
assert cfg["out"] == "hex"
assert cfg["mid"] == "hex"
def test_hex_artefact_is_larger_than_bt(self, vectors):
"""A hex intermediate doubles the payload at each layer."""
big = "A" * 5_000
sizes = {}
for mid in MIDS:
c = _core(MODE_TURBO, vectors, "hex", mid)
sizes[mid] = len(_payload(c.encrypt_text(big, USER_PWD)))
assert sizes[MID_HEX] > sizes[MID_BYTES]
def test_base64_output_is_smaller_than_hex(self, vectors):
big = "A" * 5_000
sizes = {}
for enc in ENCODINGS:
c = _core(MODE_TURBO, vectors, enc, MID_BYTES)
sizes[enc] = len(_payload(c.encrypt_text(big, USER_PWD)))
assert sizes[ENC_BASE64] < sizes[ENC_HEX]
def test_hex_payload_is_hex(self, vectors):
c = _core(MODE_TURBO, vectors, "hex", MID_BYTES)
int(_payload(c.encrypt_text("data", USER_PWD)), 16)
def test_base64_payload_is_base64(self, vectors):
import base64 as b64
c = _core(MODE_TURBO, vectors, ENC_BASE64, MID_BYTES)
b64.b64decode(_payload(c.encrypt_text("data", USER_PWD)).encode(),
validate=True)
def test_unknown_encoding_rejected(self):
with pytest.raises(ValueError):
ChaosCryptCore(MODE_TURBO, encoding="base85")
def test_unknown_mid_rejected(self):
with pytest.raises(ValueError):
ChaosCryptCore(MODE_TURBO, mid="nonsense")
def test_mid_aliases_are_accepted(self):
"""'bytes' is an accepted spelling of 'bt', and 'base' of 'base64'."""
assert ChaosCryptCore(MODE_TURBO, mid="bytes").mid == MID_BYTES
assert ChaosCryptCore(MODE_TURBO, encoding="base").encoding == ENC_BASE64
# ---------------------------------------------------------------------------
# The header decides how an artefact is read
# ---------------------------------------------------------------------------
class TestHeaderDrivesDecryption:
def test_a_misconfigured_reader_still_works(self, vectors):
"""The artefact states its own parameters; the reader need not."""
writer = _core(MODE_TURBO, vectors, ENC_BASE64, MID_HEX)
ct = writer.encrypt_text("header rules", USER_PWD)
reader = _core(MODE_TURBO, vectors, "hex", MID_BYTES) # wrong on both
assert reader.decrypt_text(ct, USER_PWD) == "header rules"
def test_headerless_input_is_rejected(self, cores):
for mode in MODES:
with pytest.raises(ChaosCryptError) as ei:
cores[mode].decrypt_text("72370655cafe", USER_PWD)
assert ei.value.code == "E017", mode
def test_malformed_payload_is_rejected(self, vectors):
from chaoscrypt._header import build_header
c = _core(MODE_TURBO, vectors)
bad = build_header(c.header_config("ciphertext")) + "zz"
with pytest.raises(ChaosCryptError) as ei:
c.decrypt_text(bad, USER_PWD)
assert ei.value.code == "E010"
# ---------------------------------------------------------------------------
# Key material must still contribute
# ---------------------------------------------------------------------------
class TestKeyMaterialContributes:
@pytest.mark.parametrize("mode", MODES)
def test_long_key_contributes(self, vectors, mode):
a = _core(mode, vectors)
b = _core(mode, vectors)
b.long_key = "0" * 4096
b._build_maps()
assert (a.encrypt_text("UPPER and lower", USER_PWD)
!= b.encrypt_text("UPPER and lower", USER_PWD))
@pytest.mark.parametrize("mode", MODES)
def test_short_key_contributes(self, vectors, mode):
a = _core(mode, vectors)
b = _core(mode, vectors)
b.short_key = "0" * 512
b._build_maps()
assert (a.encrypt_text("UPPER and lower", USER_PWD)
!= b.encrypt_text("UPPER and lower", USER_PWD))
@pytest.mark.parametrize("mode", MODES)
def test_password_contributes(self, vectors, mode):
c = _core(mode, vectors)
assert (c.encrypt_text("same", "pw-a") != c.encrypt_text("same", "pw-b"))
@pytest.mark.parametrize("mode", MODES)
def test_substitution_tables_contribute(self, vectors, mode):
a = _core(mode, vectors)
b = _core(mode, vectors)
b.upper_mapping = "ZYXWVUTSRQPONMLKJIHGFEDCBA"
b._build_maps()
# both cases present, so upper_mapping cannot be bypassed
assert (a.encrypt_text("UPPER and lower", USER_PWD)
!= b.encrypt_text("UPPER and lower", USER_PWD))
@pytest.mark.parametrize("mode", MODES)
def test_lower_mapping_contributes(self, vectors, mode):
a = _core(mode, vectors)
b = _core(mode, vectors)
b.lower_mapping = "zyxwvutsrqponmlkjihgfedcba"
b._build_maps()
assert (a.encrypt_text("UPPER and lower", USER_PWD)
!= b.encrypt_text("UPPER and lower", USER_PWD))
@pytest.mark.parametrize("mode", MODES)
def test_flip_pattern_contributes(self, vectors, mode):
a = _core(mode, vectors)
b = _core(mode, vectors)
b.flip_pattern = [0] * 10
sample = "UPPER and lower"
assert (a.encrypt_text(sample, USER_PWD)
!= b.encrypt_text(sample, USER_PWD))
# ---------------------------------------------------------------------------
# Public API
# ---------------------------------------------------------------------------
class TestPublicAPI:
@pytest.mark.parametrize("mode", MODES)
def test_facade_roundtrip(self, keyfile, mode):
cc = ChaosCrypt(key_file=keyfile, key_password=KEY_PWD,
auto_load=True, mode=mode)
ct = cc.encrypt("facade mode test", USER_PWD)
assert cc.decrypt(ct, USER_PWD) == "facade mode test"
@pytest.mark.parametrize("enc", ENCODINGS)
def test_facade_supports_encoding(self, keyfile, enc):
cc = ChaosCrypt(key_file=keyfile, key_password=KEY_PWD, auto_load=True,
mode=MODE_TURBO, encoding=enc)
ct = cc.encrypt("encoding via facade", USER_PWD)
assert cc.decrypt(ct, USER_PWD) == "encoding via facade"
@pytest.mark.parametrize("mid", MIDS)
def test_facade_supports_mid(self, keyfile, mid):
cc = ChaosCrypt(key_file=keyfile, key_password=KEY_PWD, auto_load=True,
mode=MODE_TURBO, mid=mid)
ct = cc.encrypt("mid via facade", USER_PWD)
assert cc.decrypt(ct, USER_PWD) == "mid via facade"
@pytest.mark.parametrize("mode", MODES)
def test_facade_file_roundtrip(self, keyfile, tmp_path, mode):
cc = ChaosCrypt(key_file=keyfile, key_password=KEY_PWD,
auto_load=True, mode=mode)
payload = os.urandom(1_500)
src = tmp_path / "payload.bin"
src.write_bytes(payload)
enc = cc.encrypt_file(str(src), USER_PWD)
out = cc.decrypt_file(enc, USER_PWD, str(tmp_path / "out.bin"))
assert open(out, "rb").read() == payload
# ---------------------------------------------------------------------------
# Errors, common to every mode
# ---------------------------------------------------------------------------
class TestModeErrors:
@pytest.mark.parametrize("mode", MODES)
def test_empty_plaintext_rejected(self, cores, mode):
with pytest.raises(ChaosCryptError) as ei:
cores[mode].encrypt_text("", USER_PWD)
assert ei.value.code == "E008"
@pytest.mark.parametrize("mode", MODES)
def test_empty_password_rejected(self, cores, mode):
with pytest.raises(ChaosCryptError) as ei:
cores[mode].encrypt_text("data", "")
assert ei.value.code == "E006"
def test_empty_ciphertext_rejected(self, cores):
with pytest.raises(ChaosCryptError) as ei:
cores[MODE_FAST].decrypt_text("", USER_PWD)
assert ei.value.code == "E009"
+3 -3
View File
@@ -62,7 +62,7 @@ class TestTUI:
seq = (f"5\nt.key\n{KEY_PWD}\n{KEY_PWD}\n\n"
f"1\nsecret payload\n{USER_PWD}\n\nq\n")
r1 = _run_tui(seq, str(tmp_path))
m = re.search(r"Ciphertext:\s*\n([0-9a-f]{16,})", r1.stdout)
m = re.search(r"Ciphertext:\s*\n(69CES[^\s]+)", r1.stdout)
assert m, r1.stdout
ct = m.group(1).strip()
@@ -73,7 +73,7 @@ class TestTUI:
def test_load_remembers_key_file(self, tui_dir):
seq = f"6\nt.key\n{KEY_PWD}\n\n1\nremembers\n{USER_PWD}\n\nq\n"
r = _run_tui(seq, tui_dir)
assert re.search(r"Ciphertext:\s*\n([0-9a-f]{16,})", r.stdout), r.stdout
assert re.search(r"Ciphertext:\s*\n(69CES[^\s]+)", r.stdout), r.stdout
def test_wrong_user_password_shows_error(self, tui_dir):
seq = f"6\nt.key\n{KEY_PWD}\n\n2\n{'a' * 64}\nWRONG-{USER_PWD}\n\nq\n"
@@ -97,7 +97,7 @@ class TestTUI:
seq = (f"6\nt.key\n{KEY_PWD}\n\n9\n2\n\n"
f"1\n中文内容\n{USER_PWD}\n\nq\n")
r = _run_tui(seq, tui_dir)
assert re.search(r"密文:\s*\n([0-9a-f]{16,})", r.stdout), r.stdout
assert re.search(r"密文:\s*\n(69CES[^\s]+)", r.stdout), r.stdout
def test_about_page_has_design_notes(self, tmp_path):
r = _run_tui("a\n\nq\n", str(tmp_path))
+294
View File
@@ -0,0 +1,294 @@
# -*- coding: utf-8 -*-
"""
Strict reference-vector tests.
ChaosCrypt is a self-designed construction, so unlike AES or SHA-3 there are no
FIPS or RFC vectors to check it against. What can be checked is that the format
and the algorithm do not drift: the vectors in
``vectors/chaoscrypt_reference.json`` are generated from the implementation and
then frozen. If anything changes -- a substitution table, a bit operation, a
loop bound, the header layout, an encoding -- these tests fail.
Every artefact now carries a self-describing header, so each case is checked
for three things: the header is present and consistent, the ciphertext matches
the frozen value exactly, and the payload round-trips.
"""
import pytest
from chaoscrypt._core import ChaosCryptCore
from chaoscrypt.errors import ChaosCryptError
from chaoscrypt._header import (
MAGIC, BEGIN_MARKER, END_MARKER, read_header, strip_header,
MIDS, OUTS, KIND_CIPHERTEXT,
)
from ._vectors import available, load
VECTOR_NAME = "chaoscrypt_reference"
@pytest.fixture(scope="module")
def vectors():
return load(VECTOR_NAME)
def _core_from(km, mode="fast", enc="hex", mid="bt"):
"""Build a ChaosCryptCore preloaded with fixed key material."""
c = ChaosCryptCore(mode, "hash", enc, mid)
c.upper_mapping = km["upper_mapping"]
c.lower_mapping = km["lower_mapping"]
c.digit_mapping = km["digit_mapping"]
c.equal_mapping = km["equal_mapping"]
c.flip_pattern = km["flip_pattern"]
c.long_key = km["long_key"]
c.short_key = km["short_key"]
c.digit_reverse = {v: k for k, v in c.digit_mapping.items()}
c.equal_reverse = {v: k for k, v in c.equal_mapping.items()}
c._build_maps()
c.keys_loaded = True
return c
@pytest.fixture(scope="module")
def core(vectors):
return _core_from(vectors["key_material"])
def _per_case_core(case, km):
"""A core configured the way the case was produced."""
return _core_from(km,
mode=case.get("mode", "fast"),
enc=case.get("out", "hex"),
mid=case.get("mid", "bt"))
# ---------------------------------------------------------------------------
# Vector file integrity
# ---------------------------------------------------------------------------
class TestVectorFile:
def test_vector_file_is_present(self):
assert VECTOR_NAME in available()
def test_required_sections_exist(self, vectors):
for key in ("key_material", "passwords", "cases",
"error_cases", "key_material_properties"):
assert key in vectors, f"missing section: {key}"
def test_long_key_is_4096_nibbles(self, vectors):
assert len(vectors["key_material"]["long_key"]) == 4096
def test_short_key_is_512_nibbles(self, vectors):
assert len(vectors["key_material"]["short_key"]) == 512
def test_keys_are_valid_hex(self, vectors):
int(vectors["key_material"]["long_key"], 16)
int(vectors["key_material"]["short_key"], 16)
def test_case_ids_are_unique(self, vectors):
ids = [c["id"] for c in vectors["cases"]]
assert len(ids) == len(set(ids))
def test_case_modes_are_known(self, vectors):
from chaoscrypt import MODES
for case in vectors["cases"]:
assert case.get("mode", "fast") in MODES, case["id"]
def test_case_mids_and_outs_are_known(self, vectors):
for case in vectors["cases"]:
assert case.get("mid", "bt") in MIDS, case["id"]
assert case.get("out", "hex") in OUTS, case["id"]
# ---------------------------------------------------------------------------
# Key material invariants
# ---------------------------------------------------------------------------
class TestKeyMaterialInvariants:
def test_upper_mapping_is_a_bijection(self, vectors):
m = vectors["key_material"]["upper_mapping"]
assert len(m) == 26
assert sorted(m) == sorted("ABCDEFGHIJKLMNOPQRSTUVWXYZ")
def test_lower_mapping_is_a_bijection(self, vectors):
m = vectors["key_material"]["lower_mapping"]
assert len(m) == 26
assert sorted(m) == sorted("abcdefghijklmnopqrstuvwxyz")
def test_digit_mapping_covers_all_digits(self, vectors):
m = vectors["key_material"]["digit_mapping"]
assert sorted(m.keys()) == sorted("0123456789")
assert len(set(m.values())) == 10
def test_equal_mapping_covers_padding_counts(self, vectors):
m = vectors["key_material"]["equal_mapping"]
assert sorted(m.keys()) == ["0", "1", "2", "3"]
assert len(set(m.values())) == 4
def test_flip_pattern_is_ten_bits(self, vectors):
p = vectors["key_material"]["flip_pattern"]
assert len(p) == 10
assert all(b in (0, 1) for b in p)
# ---------------------------------------------------------------------------
# Header conformance of every frozen case
# ---------------------------------------------------------------------------
class TestFrozenHeaders:
def test_every_case_starts_with_the_magic(self, vectors):
magic = MAGIC.decode()
for case in vectors["cases"]:
assert case["ciphertext"].startswith(magic), case["id"]
def test_every_case_carries_both_markers(self, vectors):
for case in vectors["cases"]:
ct = case["ciphertext"]
assert BEGIN_MARKER in ct, case["id"]
assert END_MARKER in ct, case["id"]
def test_every_case_header_parses(self, vectors):
for case in vectors["cases"]:
cfg = read_header(case["ciphertext"])
assert cfg["kind"] == KIND_CIPHERTEXT, case["id"]
def test_header_mode_matches_the_case(self, vectors):
for case in vectors["cases"]:
cfg = read_header(case["ciphertext"])
assert cfg["mode"] == case.get("mode", "fast"), case["id"]
def test_header_mid_matches_the_case(self, vectors):
"""The header's mid must match what the case says, or hex for the
character pipelines, which have no mid of their own."""
for case in vectors["cases"]:
cfg = read_header(case["ciphertext"])
mode = case.get("mode", "fast")
if mode in ("reference", "fast"):
assert cfg["mid"] == "hex", case["id"]
else:
assert cfg["mid"] == case.get("mid", "bt"), case["id"]
def test_header_out_matches_the_case(self, vectors):
for case in vectors["cases"]:
cfg = read_header(case["ciphertext"])
mode = case.get("mode", "fast")
if mode in ("reference", "fast"):
assert cfg["out"] == "hex", case["id"]
else:
assert cfg["out"] == case.get("out", "hex"), case["id"]
def test_reference_and_fast_always_report_hex(self, vectors):
"""The character pipelines ignore mid and always use hex."""
for case in vectors["cases"]:
if case.get("mode") in ("reference", "fast"):
cfg = read_header(case["ciphertext"])
assert cfg["mid"] == "hex", case["id"]
assert cfg["out"] == "hex", case["id"]
def test_payload_is_not_empty(self, vectors):
for case in vectors["cases"]:
assert strip_header(case["ciphertext"]), case["id"]
# ---------------------------------------------------------------------------
# The frozen ciphertexts themselves
# ---------------------------------------------------------------------------
class TestFrozenVectors:
def test_encryption_reproduces_frozen_ciphertext(self, vectors):
"""Encrypting the recorded plaintext must yield the recorded artefact."""
km = vectors["key_material"]
pwd = vectors["passwords"]["user_password"]
failures = []
for case in vectors["cases"]:
c = _per_case_core(case, km)
got = c.encrypt_text(case["plaintext"], pwd)
if got != case["ciphertext"]:
failures.append(
f"{case['id']}:\n expected {case['ciphertext'][:80]}\n"
f" got {got[:80]}"
)
assert not failures, (
"frozen vectors no longer match -- format or algorithm changed:\n"
+ "\n".join(failures)
)
def test_decryption_round_trips(self, vectors):
km = vectors["key_material"]
pwd = vectors["passwords"]["user_password"]
for case in vectors["cases"]:
c = _per_case_core(case, km)
got = c.decrypt_text(case["ciphertext"], pwd)
assert got == case["plaintext"], case["id"]
def test_encryption_is_deterministic(self, vectors):
km = vectors["key_material"]
pwd = vectors["passwords"]["user_password"]
for case in vectors["cases"]:
c = _per_case_core(case, km)
a = c.encrypt_text(case["plaintext"], pwd)
b = c.encrypt_text(case["plaintext"], pwd)
assert a == b, f"{case['id']} is not deterministic"
def test_wrong_password_does_not_reproduce_plaintext(self, core, vectors):
case = vectors["cases"][0]
try:
got = core.decrypt_text(case["ciphertext"], "not-the-password")
except ChaosCryptError:
return
assert got != case["plaintext"]
# ---------------------------------------------------------------------------
# Error behaviour
# ---------------------------------------------------------------------------
class TestFrozenErrorCases:
def test_error_cases_raise_expected_codes(self, core, vectors):
failures = []
for case in vectors["error_cases"]:
try:
if case["kind"] == "encrypt":
core.encrypt_text(case["plaintext"], case["password"])
else:
core.decrypt_text(case["ciphertext"], case["password"])
except ChaosCryptError as e:
if e.code != case["expect_code"]:
failures.append(
f"{case['id']}: expected {case['expect_code']}, got {e.code}"
)
else:
failures.append(
f"{case['id']}: expected {case['expect_code']}, no error raised"
)
assert not failures, "\n".join(failures)
def test_headerless_input_is_rejected(self, core, vectors):
"""The deliberate break from pre-4.2.6 material."""
with pytest.raises(ChaosCryptError) as ei:
core.decrypt_text("72370655031311011c111f261365172716020b69", "pw")
assert ei.value.code == "E017"
# ---------------------------------------------------------------------------
# Known-answer tests for the building blocks
# ---------------------------------------------------------------------------
class TestKnownAnswers:
def test_digit_mapping_encode(self, core, vectors):
kat = next(k for k in vectors["known_answer_tests"]
if k["id"] == "digit_mapping_encode")
assert core._encode_digit(kat["input"]) == kat["expected"]
def test_digit_mapping_round_trip(self, core, vectors):
kat = next(k for k in vectors["known_answer_tests"]
if k["id"] == "digit_mapping_encode")
assert core._decode_digit(kat["expected"]) == kat["input"]
def test_equal_mapping_values(self, vectors):
kat = next(k for k in vectors["known_answer_tests"]
if k["id"] == "equal_mapping_values")
assert vectors["key_material"]["equal_mapping"] == kat["expected"]
def test_substitution_round_trip(self, core):
sample = "ABCXYZabcxyz"
subbed = core._substitute_letters(sample, core.encrypt_map)
assert core._substitute_letters(subbed, core.decrypt_map) == sample
def test_case_flip_is_its_own_inverse(self, core):
sample = "AbCdEfGhIjKlMnOp"
assert core._apply_flip(core._apply_flip(sample)) == sample
@@ -0,0 +1,215 @@
{
"_comment": "ChaosCrypt frozen reference vectors for the headed format (4.2.6 onward). Every artefact carries a self-describing header: magic b'69CES', a begin marker, a JSON configuration record, an end marker, then the payload. ChaosCrypt is a self-designed construction, so no FIPS or RFC vectors exist for it; these are generated from the implementation and then frozen, which turns them into a regression guard. They are NOT a proof of strength. Regenerating them means the format or the algorithm changed, which is a compatibility break.",
"name": "chaoscrypt_reference",
"source": "Self-generated from the implementation, then frozen",
"version": "4.2.6",
"notes": [
"Key material below is fixed so the vectors are reproducible; never use it for real data.",
"Every ciphertext starts with the magic bytes b'69CES'.",
"The configuration block names the mode, the intermediate representation (mid) and the output encoding (out).",
"reference and fast share one ciphertext form and always use hex; only mode is recorded differently.",
"turbo and raw support out=hex|base and mid=bt|hex, producing distinct formats.",
"Headerless input is rejected with E017, by design."
],
"key_material": {
"upper_mapping": "BCDEFGHIJKLMNOPQRSTUVWXYZA",
"lower_mapping": "bcdefghijklmnopqrstuvwxyza",
"digit_mapping": {
"0": "A",
"1": "B",
"2": "C",
"3": "D",
"4": "E",
"5": "F",
"6": "G",
"7": "H",
"8": "I",
"9": "J"
},
"equal_mapping": {
"0": "W",
"1": "X",
"2": "Z",
"3": "Y"
},
"flip_pattern": [
1,
0,
1,
0,
0,
1,
0,
0,
1,
0
],
"long_key": "39d65637ec0f62b69ca5d3c5ab08385d533d000dc2d8984d23406b2cb30e3ce304ab21201994888a838d10100ff5688702850c3cb7c828123be21f3f0fca661065db7b80d40b05717d7c18d8374e925044a9ce53e9445c1d12bed49340b1bc8e44fd81c3a63e933da598f9384fc25cded0d8c5e9d5a1462beeca11d631f5e65e578e95bcf67600c993436722dd4cd582487efff016f034c54be236ad3562ddcff16fc53e34597734c8326c54326343c6f4bda1cf82b884080a521dae535b7a6b45ba3350b56ea5b61fe1757b8f51328001975fd898057a6d7bcae3225d9b8742539b29023476500cccee48835dac749908dbf1003bcd754093a6a8ca4bf8f0159716e7c28877c5c7f66fd3885604c94a100372b691aff5811fc75fa91573e8677e56663fecf2314f1fada7239737396398228417a72c7335fb3af6949b3925d6127f2461d711dbf0a45fef7f4fe71ea981cfff4ccc51e52ab46af1fe98c24365c18fa8e368b891c9fb38307f627b877c73487c9fce2250eea6c6be1bdeea24500548b902e9795f8290907bbef77dcf05251d3e412cbac121a1703abc2329f091e27f48736b52db793a8cf03016aec910386ea811dbded8af82cbb1ed331a4e67e24441d95c69607b4f0278b398fc7bb44b12da5bca48bdfba3506e4604615c6ec426ebd4db7996d889bdd53088105d916d84f37b7f781fd49455d533356af6b85d15a3eec3047f933d0212cf53483c752cfc0eea4bca27fe2bd7fded49851324d80c02d8145e4bf5f90d479436850e37875fac00257db3e53b3a0fb3b782338113a1cd7b554e0fe606195a8a51e2898f8469d20b4896f928d113b7bc82ef0dd3b7d8237f98cc7044cb94c2ef513f32de92d59f0aa65f201528f2c1a5b2c18d8db7e2b87755cb273317133bdaf398e229b8bc519cc753b381f5555309763ceeaaf8134e7e9d14707de6382af9664ec9d6d3d0244d241c23070362b8f0b1497f5b6182b2bd3a60f7f03463ffa2e79c68efe169453489f153cc65251e140e72c7c3752c515b604238f65e5ba06dcffce9f9b1566934ca052eb30026b8d4236623c157f20ca480a53b22f95e979471d0c05b0b8f3755833b9396241679eb78c63ccd2170b3213660c0d2275f7ac3f4618f8a688e35d1a59cdd0177bcb23c4a283f487bcafc63ce5c1cba9baec57093cf12c8dd0c8d7f352333cd660814c94b27385445390056d75077d33c6cd977fa5f6aa19ebea84890bdc55400e02d8337b4097b1532e77fe5b7e1b3d9426ceb3417b0a2a481c1aa8c84692d34f2fa29c3c90cfd0bcb0fe227fc63fa8877e38ad2d8ac8a198c331c24c73de46c4b7f9fc157953b8c8964caedbd89305b443dc178aee57874b06ecc0b208eeeab632167047a105aa67471df64d17f6deddfc77781c6c1c9945a7125bee0eb19c50cd560311ebc0e62ae18eb197964e471dc09ca2fc4c135cd924b69b5006eb6ff0904cf064f64a54b94db3c72ba607554b74bbca4efb4fe42238eb4ffdf5fda2a1ab2675c3de0dd8da5f759c8648ed4e2ee68a1571290b7962b53f7710f3dbacd826971c1bc019f34b654e51aeb24f936dcf38ca7e87203a9ea57b21dc865b79d238092e49c156c5bc2e0abc2c47822546963ef3a77bbcf7ab70da0c27e209a1054160897af67042c326c055ec7a55dfe74a8d367a57a32ee3569e58c0674d58a95d8116d9082f463727987e5279d5fb27a54849feb1021f1649f55c56a7edd5017f6255ee7e2c309556992c127bd7ae270233b24f0c648cb499624e79184a7936da6108af26b47fa137cec35b5130b62039e3946ec427d9b34d9ebeabe0a95c518f06934a32c38ce2162e276757a2362cc5eb27a8c31be14c3b1d3d5611c752ff894944d3ea637a87eb2a286d8c7400b3c1a691a224e965ce2ad13ea95305c68e60691793c696887a74b8952e8434f510fdbb0ba7e0f3322a4da801db599a8210cf0a0a9ca1e296c25402f606fcbf45f06a22f2bfeb44c62a2680bce5c6e63ecd57bc4e3170111b00bd5fcf1d8feb5e21dbfd671d5826c9dfc7188689f99b05012629dd0d29fb291e25560729f017a2207949fa873d74d1a17251382a11feae73755614c53291674945312378fdc2b79d1078244f5ae4ee44f7a8e7f27d8b4ce1b1c19415cfa3d8a2c8b92041416da7556f27181d7583de84fd21129afeab0707dcce01e03cb3d69258edaf8c88535b828eb0651eba05dec330d3c2a68629c7498d47188238f3f216b4f848ed5e2c6c9cdef330ec2e58fdf89a4e2bcc3c114ab06d15541d9cac8947c9562ac5cfb2bd7ac56f4947b43f5f614aa409d84addcd325f696976caea9ff4b951e4c920c184cf4963c8cbb92e580fb78e41ec762e3f7f7bea9bb9488b93d524c55c4ca017c632ce12c381e73aaf9359346ee53c3cfd9922b41e5034031781f7b698c411e23d56e13327f316ac807c1d56c815915a56c3ad044c15070ff2c28ee2381fea84f36e70b039988ba7dc6cb55f698afc4859da08475197620a56c113f702e90f41f20708e853f0be81d5080ce7dd3683d3f1386e37c26e06161cf4500e5cc8bbd6f7e243e5733abdfb2e9554c22c5e16b4ecd6241e326e460765d874f578e7e720b00fb7f0ad725551bba2912e85d895bc705032c18bf3e8c6ad3587d39d2f00ae869a8da03afdb581d588af5eee8b69e1de6e1a5fda79946a05dc3bf9fcaae92b4b03b9d75bf6f61a6f35f1d3f4f293b2f0477d2e8dd90f1c51bba82beccd388d3f6a3cb6613ac1e4e8fb59a6d8844d1c15496d70e33a820ed5d9a027b2f3581d5e2b32ef3cd8eb229c728b138096811ad9b66868ec780fb03d4e6c9585329cf5635eca3fc5b7e4f6759b9b4278330280b6e940756153481fe",
"short_key": "cafb66ae19518dd63547f87adbf4d26a4f035480433cf7f9a2a19f846f152b8eabfc7673995f75ff3a2e90107432921ae92c06af87e549d1983684f89ec7964ca4d001671c483a93ced8b665e94310e375ec4933e04bce3c67bc895cdaa7c593d50a0c3b19f6efc5e3a88a0371904615899e71b481b6cf077f77f681d74fe2eadb666d3fdfda87e88d50ae94f2fc174958bf4e33954a685eba7a7c5d81816ebd47e56d6d8a8a246b0f0abc219bc3da5b790c12461475855d3fef3d3247b8c08d1d7326419c3e4df22f1138cbc39cb01da917cc8dacd97be1c2dd6bef4b626c9d8fafa25479735c02789006d1905f29d2c666114fc802abd19a095170e9e2c6eb"
},
"passwords": {
"user_password": "reference-user-password",
"key_password": "reference-key-password"
},
"key_material_properties": {
"long_key_length": 4096,
"short_key_length": 512,
"digit_mapping_size": 10,
"equal_mapping_size": 4,
"flip_pattern_length": 10,
"upper_mapping_is_bijection": true,
"lower_mapping_is_bijection": true
},
"cases": [
{
"id": "text_ascii_short",
"kind": "text",
"plaintext": "hello",
"ciphertext": "69CES385aeff1f4179a744c8fb0c5ae4702d325f6230d059f4251135c2536409dee93{\"alg\":\"chaoscrypt\",\"b64\":true,\"cache\":\"hash\",\"compact\":false,\"flip\":\"conditional\",\"flipbits\":10,\"kdf\":\"expand\",\"keybits\":16384,\"keyshort\":2048,\"kind\":\"ciphertext\",\"ksum\":\"8007e271aea2b261\",\"lib\":\"4.2.6\",\"mid\":\"hex\",\"mode\":\"fast\",\"order\":\"base64>subst>flip>reverse>xor>xor\",\"out\":\"hex\",\"subst\":\"bijective\",\"utf8\":true,\"v\":1,\"xor_layers\":2}2025ea4e4b4b93803f2ccadeaf318d1957ce42ff5409410f660348be96a4c0f272370655031311011c111f261365172716020b69"
},
{
"id": "text_ascii_long",
"kind": "text",
"plaintext": "The quick brown fox jumps over the lazy dog.",
"ciphertext": "69CES385aeff1f4179a744c8fb0c5ae4702d325f6230d059f4251135c2536409dee93{\"alg\":\"chaoscrypt\",\"b64\":true,\"cache\":\"hash\",\"compact\":false,\"flip\":\"conditional\",\"flipbits\":10,\"kdf\":\"expand\",\"keybits\":16384,\"keyshort\":2048,\"kind\":\"ciphertext\",\"ksum\":\"8007e271aea2b261\",\"lib\":\"4.2.6\",\"mid\":\"hex\",\"mode\":\"fast\",\"order\":\"base64>subst>flip>reverse>xor>xor\",\"out\":\"hex\",\"subst\":\"bijective\",\"utf8\":true,\"v\":1,\"xor_layers\":2}2025ea4e4b4b93803f2ccadeaf318d1957ce42ff5409410f660348be96a4c0f272620757011113021e151f26116d1377165244424335566654761112461771556c355415785650231457101775157e77517a025a53761c646866101570571471047562634110750b1246147e412617017552161472621350437112030331791f7d41524563721555011276167f5f7443172460066114177e1036286067"
},
{
"id": "text_unicode",
"kind": "text",
"plaintext": "ChaosCrypt 混沌加密世界",
"ciphertext": "69CES385aeff1f4179a744c8fb0c5ae4702d325f6230d059f4251135c2536409dee93{\"alg\":\"chaoscrypt\",\"b64\":true,\"cache\":\"hash\",\"compact\":false,\"flip\":\"conditional\",\"flipbits\":10,\"kdf\":\"expand\",\"keybits\":16384,\"keyshort\":2048,\"kind\":\"ciphertext\",\"ksum\":\"8007e271aea2b261\",\"lib\":\"4.2.6\",\"mid\":\"hex\",\"mode\":\"fast\",\"order\":\"base64>subst>flip>reverse>xor>xor\",\"out\":\"hex\",\"subst\":\"bijective\",\"utf8\":true,\"v\":1,\"xor_layers\":2}2025ea4e4b4b93803f2ccadeaf318d1957ce42ff5409410f660348be96a4c0f274370557031d120a1d151f2712611627175042144167573654701314441c70016f6c57477b0151271757154774157f27517c015453771c646f31131270561776042267644115745c104e13744075170b74065a6000"
},
{
"id": "text_single_char",
"kind": "text",
"plaintext": "a",
"ciphertext": "69CES385aeff1f4179a744c8fb0c5ae4702d325f6230d059f4251135c2536409dee93{\"alg\":\"chaoscrypt\",\"b64\":true,\"cache\":\"hash\",\"compact\":false,\"flip\":\"conditional\",\"flipbits\":10,\"kdf\":\"expand\",\"keybits\":16384,\"keyshort\":2048,\"kind\":\"ciphertext\",\"ksum\":\"8007e271aea2b261\",\"lib\":\"4.2.6\",\"mid\":\"hex\",\"mode\":\"fast\",\"order\":\"base64>subst>flip>reverse>xor>xor\",\"out\":\"hex\",\"subst\":\"bijective\",\"utf8\":true,\"v\":1,\"xor_layers\":2}2025ea4e4b4b93803f2ccadeaf318d1957ce42ff5409410f660348be96a4c0f274640757021c13505466"
},
{
"id": "text_repeated",
"kind": "text",
"plaintext": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"ciphertext": "69CES385aeff1f4179a744c8fb0c5ae4702d325f6230d059f4251135c2536409dee93{\"alg\":\"chaoscrypt\",\"b64\":true,\"cache\":\"hash\",\"compact\":false,\"flip\":\"conditional\",\"flipbits\":10,\"kdf\":\"expand\",\"keybits\":16384,\"keyshort\":2048,\"kind\":\"ciphertext\",\"ksum\":\"8007e271aea2b261\",\"lib\":\"4.2.6\",\"mid\":\"hex\",\"mode\":\"fast\",\"order\":\"base64>subst>flip>reverse>xor>xor\",\"out\":\"hex\",\"subst\":\"bijective\",\"utf8\":true,\"v\":1,\"xor_layers\":2}2025ea4e4b4b93803f2ccadeaf318d1957ce42ff5409410f660348be96a4c0f21274143211731f451f501214035306307221650654071643044e141c761263457215564216426104660774101143132651606652447c0155704451404374112c72007f065253704c636161101573574175527463614412750f17404676447742062551131572621c55127111030066291a2a1051176074465357117341795025111c716551601344724461631713734d437053420843404710141d321555157c7f160f061440712c435f735578130d4d136d177806666344430411461440504d434e6173062b6240115d7160546266070421735513437666164406070856630610527a40167463456f1e447457735231046c467403136a0b73431044640d611f4121521613155515435d111302137e525a716c03"
},
{
"id": "turbo_hex_default",
"kind": "text",
"mode": "turbo",
"out": "hex",
"mid": "bt",
"note": "turbo in its default form",
"plaintext": "mode coverage sample",
"ciphertext": "69CES385aeff1f4179a744c8fb0c5ae4702d325f6230d059f4251135c2536409dee93{\"alg\":\"chaoscrypt\",\"b64\":true,\"cache\":\"hash\",\"compact\":true,\"flip\":\"conditional\",\"flipbits\":10,\"kdf\":\"shake256\",\"keybits\":16384,\"keyshort\":2048,\"kind\":\"ciphertext\",\"ksum\":\"8007e271aea2b261\",\"lib\":\"4.2.6\",\"mid\":\"bt\",\"mode\":\"turbo\",\"order\":\"base64>subst>flip>reverse>xor>xor\",\"out\":\"hex\",\"subst\":\"bijective\",\"utf8\":true,\"v\":1,\"xor_layers\":2}2025ea4e4b4b93803f2ccadeaf318d1957ce42ff5409410f660348be96a4c0f2568d8a131c130eef3c78ac317ed0f40bb7da2bb3"
},
{
"id": "turbo_hex_mid",
"kind": "text",
"mode": "turbo",
"out": "hex",
"mid": "hex",
"note": "turbo with a hex intermediate",
"plaintext": "mode coverage sample",
"ciphertext": "69CES385aeff1f4179a744c8fb0c5ae4702d325f6230d059f4251135c2536409dee93{\"alg\":\"chaoscrypt\",\"b64\":true,\"cache\":\"hash\",\"compact\":true,\"flip\":\"conditional\",\"flipbits\":10,\"kdf\":\"shake256\",\"keybits\":16384,\"keyshort\":2048,\"kind\":\"ciphertext\",\"ksum\":\"8007e271aea2b261\",\"lib\":\"4.2.6\",\"mid\":\"hex\",\"mode\":\"turbo\",\"order\":\"base64>subst>flip>reverse>xor>xor\",\"out\":\"hex\",\"subst\":\"bijective\",\"utf8\":true,\"v\":1,\"xor_layers\":2}2025ea4e4b4b93803f2ccadeaf318d1957ce42ff5409410f660348be96a4c0f2d6d808fc5bca259bec4b164a17418bb8b3ca098e9207e8a3aaf218b05faa270bd512f58b92372a07415e5c035d86277a0d971666c504ff9aa31519dce9f3a38f3bfae3f4f4934fb1ae92a1c57c55a216"
},
{
"id": "turbo_base64_default",
"kind": "text",
"mode": "turbo",
"out": "base",
"mid": "bt",
"note": "turbo with base64 output",
"plaintext": "mode coverage sample",
"ciphertext": "69CES385aeff1f4179a744c8fb0c5ae4702d325f6230d059f4251135c2536409dee93{\"alg\":\"chaoscrypt\",\"b64\":true,\"cache\":\"hash\",\"compact\":true,\"flip\":\"conditional\",\"flipbits\":10,\"kdf\":\"shake256\",\"keybits\":16384,\"keyshort\":2048,\"kind\":\"ciphertext\",\"ksum\":\"8007e271aea2b261\",\"lib\":\"4.2.6\",\"mid\":\"bt\",\"mode\":\"turbo\",\"order\":\"base64>subst>flip>reverse>xor>xor\",\"out\":\"base\",\"subst\":\"bijective\",\"utf8\":true,\"v\":1,\"xor_layers\":2}2025ea4e4b4b93803f2ccadeaf318d1957ce42ff5409410f660348be96a4c0f2Vo2KExwTDu88eKwxftD0C7faK7M="
},
{
"id": "raw_hex_default",
"kind": "text",
"mode": "raw",
"out": "hex",
"mid": "bt",
"note": "raw in its default form",
"plaintext": "mode coverage sample",
"ciphertext": "69CES385aeff1f4179a744c8fb0c5ae4702d325f6230d059f4251135c2536409dee93{\"alg\":\"chaoscrypt\",\"b64\":true,\"cache\":\"hash\",\"compact\":true,\"flip\":\"conditional\",\"flipbits\":10,\"kdf\":\"shake256\",\"keybits\":16384,\"keyshort\":2048,\"kind\":\"ciphertext\",\"ksum\":\"8007e271aea2b261\",\"lib\":\"4.2.6\",\"mid\":\"bt\",\"mode\":\"raw\",\"order\":\"base64>subst>flip>reverse>xor>xor\",\"out\":\"hex\",\"subst\":\"bijective\",\"utf8\":true,\"v\":1,\"xor_layers\":2}2025ea4e4b4b93803f2ccadeaf318d1957ce42ff5409410f660348be96a4c0f2f694f4e8672f3fc16483d837efbb6d298fa015a3"
},
{
"id": "raw_hex_mid",
"kind": "text",
"mode": "raw",
"out": "hex",
"mid": "hex",
"note": "raw with a hex intermediate",
"plaintext": "mode coverage sample",
"ciphertext": "69CES385aeff1f4179a744c8fb0c5ae4702d325f6230d059f4251135c2536409dee93{\"alg\":\"chaoscrypt\",\"b64\":true,\"cache\":\"hash\",\"compact\":true,\"flip\":\"conditional\",\"flipbits\":10,\"kdf\":\"shake256\",\"keybits\":16384,\"keyshort\":2048,\"kind\":\"ciphertext\",\"ksum\":\"8007e271aea2b261\",\"lib\":\"4.2.6\",\"mid\":\"hex\",\"mode\":\"raw\",\"order\":\"base64>subst>flip>reverse>xor>xor\",\"out\":\"hex\",\"subst\":\"bijective\",\"utf8\":true,\"v\":1,\"xor_layers\":2}2025ea4e4b4b93803f2ccadeaf318d1957ce42ff5409410f660348be96a4c0f267847ae69097a7286bc9d3e865d9f336ab78f3810b03b12184d10e44474079beb9a471f1d1d3b13a91808e0f5c111cad9b738545f48d51545a3f25edce7570b95060bcb456fda92bddbf60242457696c"
},
{
"id": "raw_base64_default",
"kind": "text",
"mode": "raw",
"out": "base",
"mid": "bt",
"note": "raw with base64 output",
"plaintext": "mode coverage sample",
"ciphertext": "69CES385aeff1f4179a744c8fb0c5ae4702d325f6230d059f4251135c2536409dee93{\"alg\":\"chaoscrypt\",\"b64\":true,\"cache\":\"hash\",\"compact\":true,\"flip\":\"conditional\",\"flipbits\":10,\"kdf\":\"shake256\",\"keybits\":16384,\"keyshort\":2048,\"kind\":\"ciphertext\",\"ksum\":\"8007e271aea2b261\",\"lib\":\"4.2.6\",\"mid\":\"bt\",\"mode\":\"raw\",\"order\":\"base64>subst>flip>reverse>xor>xor\",\"out\":\"base\",\"subst\":\"bijective\",\"utf8\":true,\"v\":1,\"xor_layers\":2}2025ea4e4b4b93803f2ccadeaf318d1957ce42ff5409410f660348be96a4c0f29pT06GcvP8Fkg9g377ttKY+gFaM="
}
],
"error_cases": [
{
"id": "empty_plaintext_rejected",
"kind": "encrypt",
"plaintext": "",
"password": "reference-user-password",
"expect_code": "E008",
"note": "Empty plaintext raises ChaosCrypt_ERR_EmptyPlaintext_E008."
},
{
"id": "empty_password_rejected",
"kind": "encrypt",
"plaintext": "hello",
"password": "",
"expect_code": "E006",
"note": "Empty encryption password raises ChaosCrypt_ERR_EmptyPassword_E006."
},
{
"id": "headerless_input_rejected",
"kind": "decrypt",
"ciphertext": "72370655031311011c111f261365172716020b69",
"password": "reference-user-password",
"expect_code": "E017",
"note": "Input without the magic header is not a CES artefact. This is the deliberate break from pre-4.2.6 material."
},
{
"id": "malformed_header_rejected",
"kind": "decrypt",
"ciphertext": "69CES0000000000000000000000000000000000000000000000000000000000000000{}000000000000000000000000000000000000000000000000000000000000000000",
"password": "reference-user-password",
"expect_code": "E018",
"note": "A bad marker or unusable JSON raises ChaosCrypt_ERR_MalformedHeader_E018."
},
{
"id": "empty_ciphertext_rejected",
"kind": "decrypt",
"ciphertext": "",
"password": "reference-user-password",
"expect_code": "E009",
"note": "Empty ciphertext raises ChaosCrypt_ERR_EmptyCiphertext_E009."
}
],
"known_answer_tests": [
{
"id": "digit_mapping_encode",
"input": "0123456789",
"expected": "ABCDEFGHIJ",
"note": "_encode_digit maps each decimal digit through digit_mapping."
},
{
"id": "equal_mapping_values",
"expected": {
"0": "W",
"1": "X",
"2": "Z",
"3": "Y"
},
"note": "equal_mapping maps padding counts to these distinct characters."
}
]
}
+80 -4
View File
@@ -15,7 +15,8 @@ import os
import sys
from typing import Optional
from . import DEFAULT_KEY_FILE, __version__, ChaosCrypt
from . import (DEFAULT_KEY_FILE, __version__, ChaosCrypt, MODES,
DEFAULT_MODE, ENCODINGS, DEFAULT_ENCODING)
from .errors import ChaosCryptError
from .i18n import DEFAULT_LANG, LANG_NAMES, t
@@ -135,10 +136,14 @@ class TUI:
"""Menu-driven bilingual interface over :class:`~chaoscrypt.ChaosCrypt`."""
def __init__(self, lang: str = DEFAULT_LANG,
key_file: str = DEFAULT_KEY_FILE) -> None:
key_file: str = DEFAULT_KEY_FILE,
mode: str = DEFAULT_MODE,
encoding: str = DEFAULT_ENCODING) -> None:
self.lang = lang if lang in LANG_NAMES else DEFAULT_LANG
self.key_file = key_file
self.cc = ChaosCrypt()
self.mode = mode if mode in MODES else DEFAULT_MODE
self.encoding = encoding if encoding in ENCODINGS else DEFAULT_ENCODING
self.cc = ChaosCrypt(mode=self.mode, encoding=self.encoding)
self.key_password: Optional[str] = None
# ------------------------------------------------------------------ view
@@ -162,7 +167,7 @@ class TUI:
if self.cc.loaded
else c("[ ] " + self._tr("no_key_loaded"), "red")
)
print(f"\n{state} {c(shown, 'dim')}")
print(f"\n{state} {c(shown, 'dim')} {c('[' + self.mode + ']', 'yellow')}")
def _print_error(self, exc: Exception) -> None:
"""Render a unified error, with a hint where one applies."""
@@ -190,6 +195,8 @@ class TUI:
("7", "menu_keyinfo"),
("8", "menu_chpwd"),
("9", "menu_lang"),
("m", "menu_mode"),
("e", "menu_encoding"),
("a", "menu_about"),
("q", "menu_quit"),
]
@@ -361,6 +368,8 @@ class TUI:
("info_short_key",
f"{info['short_key_length']} {self._tr('characters')}"),
("info_loaded", self._tr("yes")),
("info_mode", self.mode),
("info_encoding", self.encoding),
]
print()
print(c(_rule(), "dim"))
@@ -405,6 +414,69 @@ class TUI:
self.lang = choice
print(c(f" -> {LANG_NAMES[self.lang]}", "green"))
def action_mode(self) -> None:
"""Switch the performance mode of the active core."""
print()
for i, name in enumerate(MODES, 1):
mark = "*" if name == self.mode else " "
desc = self._tr(f"mode_{name}_desc")
print(f" {c('[' + str(i) + ']', 'cyan')} {mark} {desc}")
default_index = str(MODES.index(self.mode) + 1)
choice = _ask(self._tr("mode_prompt"), default_index)
try:
idx = int(choice) - 1
if 0 <= idx < len(MODES):
self.mode = MODES[idx]
except ValueError:
if choice in MODES:
self.mode = choice
# Rebuild the core so the new mode takes effect, then reload the key
# if one was already loaded so the user does not have to re-enter the
# password.
was_loaded = self.cc.loaded
path = self.cc.key_file or self.key_file
pwd = self.key_password
self.cc = ChaosCrypt(mode=self.mode, encoding=self.encoding)
if was_loaded and path and pwd:
try:
self.cc.load(path, pwd)
except ChaosCryptError:
pass
print(c(f" -> {self._tr('mode_changed')} {self.mode}", "green"))
def action_encoding(self) -> None:
"""Switch the output encoding (turbo and raw only)."""
print()
for i, name in enumerate(ENCODINGS, 1):
mark = "*" if name == self.encoding else " "
desc = self._tr(f"encoding_{name}_desc")
print(f" {c('[' + str(i) + ']', 'cyan')} {mark} {desc}")
print(c(" " + self._tr("encoding_note"), "dim"))
default_index = str(ENCODINGS.index(self.encoding) + 1)
choice = _ask(self._tr("encoding_prompt"), default_index)
try:
idx = int(choice) - 1
if 0 <= idx < len(ENCODINGS):
self.encoding = ENCODINGS[idx]
except ValueError:
if choice in ENCODINGS:
self.encoding = choice
# Rebuild so the new encoding applies, then restore the loaded key.
was_loaded = self.cc.loaded
path = self.cc.key_file or self.key_file
pwd = self.key_password
self.cc = ChaosCrypt(mode=self.mode, encoding=self.encoding)
if was_loaded and path and pwd:
try:
self.cc.load(path, pwd)
except ChaosCryptError:
pass
print(c(f" -> {self._tr('encoding_changed')} {self.encoding}", "green"))
def action_about(self) -> None:
print()
print(c(self._tr("about_body"), "cyan"))
@@ -439,6 +511,10 @@ class TUI:
self.action_chpwd()
elif choice == "9":
self.action_lang()
elif choice in ("m", "mode"):
self.action_mode()
elif choice in ("e", "encoding"):
self.action_encoding()
elif choice in ("a", "about"):
self.action_about()
elif choice in ("q", "quit", "exit"):
+122
View File
@@ -21,6 +21,12 @@ from chaoscrypt import ChaosCryptError # base error class
| `decrypt` | function | One-shot decrypt using a key file |
| `create_key` | function | One-shot key file generation |
| `DEFAULT_KEY_FILE` | constant | `"encryption.key"` |
| `MODES` | constant | Tuple of the four mode names |
| `DEFAULT_MODE` | constant | `"fast"` |
| `MODE_REFERENCE` | constant | `"reference"` |
| `MODE_FAST` | constant | `"fast"` |
| `MODE_TURBO` | constant | `"turbo"` |
| `MODE_RAW` | constant | `"raw"` |
| `KEYFILE_VERSION` | constant | On-disk key file format version (`1`) |
| `__version__` | constant | Library version string |
| `__license__` | constant | `"MIT"` |
@@ -50,6 +56,9 @@ ChaosCrypt(
| `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 |
| `mode` | `str` | `"fast"` | Performance mode: `reference`, `fast`, `turbo` or `raw` |
| `encoding` | `str` | `"hex"` | Output encoding for `turbo`/`raw`: `hex` or `base64` (also accepted as `base`) |
| `mid` | `str` | `"bt"` | Intermediate representation for `turbo`/`raw`: `bt` or `hex` (also accepted as `bytes`) |
When `auto_load=True` and the file cannot be loaded, the corresponding
exception is raised from the constructor.
@@ -292,6 +301,117 @@ compatibility guarantee.
---
## Performance modes
Four modes, plus two settings that apply to the two byte-pipeline modes.
| Constant | Value | Pipeline | Ciphertext |
|---|---|---|---|
| `MODE_REFERENCE` | `"reference"` | original algorithm, character pipeline | hex, 5.33x |
| `MODE_FAST` | `"fast"` | same algorithm, bulk operations | hex, 5.33x |
| `MODE_TURBO` | `"turbo"` | SHAKE256 keystream, byte pipeline | 2.00x / 1.33x |
| `MODE_RAW` | `"raw"` | SHAKE256 plus the long-key layer | 2.00x / 1.33x |
```python
from chaoscrypt import ChaosCrypt, MODES, DEFAULT_MODE
print(MODES) # ('reference', 'fast', 'turbo', 'raw')
print(DEFAULT_MODE) # 'fast'
```
### Settings for the byte-pipeline modes
| Constant | Value | Applies to | Meaning |
|---|---|---|---|
| `ENC_HEX` | `"hex"` | `turbo`, `raw` | Two characters per octet (2.00x) |
| `ENC_BASE64` | `"base64"` | `turbo`, `raw` | Four characters per three octets (1.33x) |
| `MID_BYTES` | `"bt"` | `turbo`, `raw` | XOR layers exchange raw bytes |
| `MID_HEX` | `"hex"` | `turbo`, `raw` | XOR layers exchange hexadecimal text |
```python
from chaoscrypt import ChaosCrypt
cc = ChaosCrypt(mode="raw", encoding="base64", mid="bt")
cc.load("my.key", "key-password")
token = cc.encrypt("hello", "user-password")
```
```python
from chaoscrypt import ChaosCryptCore, MODE_TURBO, ENC_BASE64, MID_HEX
core = ChaosCryptCore(MODE_TURBO, "hash", ENC_BASE64, MID_HEX)
core.generate_keymaterial()
token = core.encrypt_text("hello", "password")
assert core.decrypt_text(token, "password") == "hello"
```
### Which mode to choose
| If you… | Use |
|---|---|
| Are not sure | `fast` — the default |
| Need maximum speed from a standardised keystream primitive | `raw` with `mid="bt"` |
| Need the smallest ciphertext | `turbo` or `raw` with `encoding="base64"` |
| Need to interoperate with the character pipeline's shape | `mid="hex"` |
| Need a payload byte-compatible with pre-4.2.6 material | `reference` or `fast` |
`fast` performs the same arithmetic as `reference` and produces the same bytes;
only the implementation differs. `turbo` and `raw` change the algorithm and
define their own formats.
> **Artefacts are not interchangeable between mode families**, and `turbo`/`raw`
> artefacts are also specific to their `encoding` and `mid`. The header records
> all three, so a reader configured differently still reads the artefact
> correctly — the ordinary decrypt takes its parameters from the header.
An unrecognised `mode`, `encoding` or `mid` raises `ValueError` at construction.
## Reading pre-4.2.6 artefacts
Artefacts written before the header existed have none, and are rejected by the
ordinary path with `E017`. They are read through the compatibility API, which
synthesises a minimal header and then uses the ordinary path.
```python
from chaoscrypt import ChaosCrypt
cc = ChaosCrypt(key_file="my.key", key_password="kf-pwd", auto_load=True)
# a ciphertext with no header
plain = cc.decrypt_legacy(old_ciphertext, "user-password")
# if you know it is a legacy key file
cc.load_legacy_keys(old_key_text, "key-password")
# let the library work out which it is
plain = cc.decrypt_legacy_auto(old_ciphertext, "user-password")
# migrate once, then use the modern path
open("new.key", "w", encoding="utf-8").write(
cc.wrap_legacy(old_key_text, is_key=True)
)
```
| Method | Purpose |
|---|---|
| `wrap_legacy(text, is_key=False)` | Prefix a minimal header; the payload is untouched. Idempotent. |
| `decrypt_legacy(text, password, is_key=False)` | Read an artefact that may predate the header |
| `decrypt_legacy_auto(text, password)` | As above, probing whether the input is a key file or a ciphertext |
| `load_legacy_keys(text, key_password)` | Load a pre-header key file |
`is_old` in the synthesised header means every other field is ignored; the
legacy path tries `fast` and falls back to `reference`. Both implement the
original algorithm.
> The compatibility API is a **wrapper** around the ordinary path, never a
> lenient branch inside it. Passing headerless input to `decrypt` still raises
> `E017`.
See [FORMAT.md §12](FORMAT.md) for the legacy standard.
---
## Error hierarchy
Every error is a subclass of `ChaosCryptError`, so a single `except` clause
@@ -326,6 +446,8 @@ except ChaosCryptError as e:
| `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 |
| `E017` | `ChaosCrypt_ERR_MissingMagicHeader_E017` | Input is not a CES artefact |
| `E018` | `ChaosCrypt_ERR_MalformedHeader_E018` | Header unusable, or `kind` mismatch |
Codes are stable and safe to branch on. The human-readable portion of the
message may be reworded between minor releases.
+618
View File
@@ -0,0 +1,618 @@
# CES Artifact Format Specification
**Normative reference for the ChaosCrypt (CES) container format**
| | |
|---|---|
| Format version | 1 |
| Status | Normative |
| Applies to | Key files and ciphertexts produced from 4.2.6 onward |
| Library | `chaoscrypt` |
---
## 1. Scope
This document specifies the byte-level layout of every artefact the library
produces. It is the authority for implementers: where this document and the
code disagree, this document is wrong and the code is to be fixed.
It defines:
- the fixed magic and delimiter values;
- the layout of the self-describing header;
- the complete field set of the configuration record;
- the payload that follows;
- the conformance requirements a reader must enforce.
It does **not** describe the cipher itself. For the algorithm see
[SECURITY.md](../SECURITY.md); for performance see [benchmark.md](benchmark.md).
---
## 2. Design rationale
Every artefact carries a header that states how it was produced. The reader
never infers a parameter from context and never guesses.
Earlier revisions left the mode and encoding to the caller's memory. That is a
silent-corruption hazard: a ciphertext decrypted under the wrong mode yields
garbage that is indistinguishable from a wrong password. Recording the
parameters alongside the artefact removes the ambiguity, and rejecting
headerless input removes the guesswork entirely.
The consequence is deliberate and absolute: **input without a valid header is
rejected, not interpreted.**
---
## 3. Fixed values
These byte sequences are constants of the format. They are reproduced in three
representations for convenience; all three denote the same octets.
### 3.1 Magic
| Representation | Value |
|---|---|
| Bytes | `b"69CES"` |
| Hex | `3639434553` |
| Decimal byte list | `[54, 57, 67, 69, 83]` |
Length: 5 octets. Position: the first octet of every artefact.
### 3.2 Begin marker
```
385aeff1f4179a744c8fb0c5ae4702d325f6230d059f4251135c2536409dee93
```
64 characters of lowercase hexadecimal. Written verbatim; it is **not** decoded
before comparison.
### 3.3 End marker
```
2025ea4e4b4b93803f2ccadeaf318d1957ce42ff5409410f660348be96a4c0f2
```
64 characters of lowercase hexadecimal. Written verbatim.
> **Note.** Both markers are fixed constants of format version 1. They are
> delimiters, not integrity checks: they carry no signature semantics and do
> not authenticate the payload. Message integrity, where required, is provided
> by the cipher and by an external MAC.
---
## 4. Container layout
An artefact is a single character string with five regions:
```
+-------------------------------------------------------------------+
| MAGIC "69CES" 5 octets |
+-------------------------------------------------------------------+
| BEGIN MARKER 64 hex chars |
+-------------------------------------------------------------------+
| CONFIGURATION UTF-8 JSON object variable |
+-------------------------------------------------------------------+
| END MARKER 64 hex chars |
+-------------------------------------------------------------------+
| PAYLOAD key material or ciphertext variable |
+-------------------------------------------------------------------+
```
The three fixed regions are literals. Only the configuration and the payload
vary between artefacts.
### 4.1 Formal grammar
```
artifact = MAGIC begin-marker config end-marker payload
MAGIC = "69CES"
begin-marker= %s"385aeff1f4179a744c8fb0c5ae4702d325f6230d059f4251135c2536409dee93"
end-marker = %s"2025ea4e4b4b93803f2ccadeaf318d1957ce42ff5409410f660348be96a4c0f2"
config = <UTF-8 encoded JSON object, see section 5>
payload = <encoding-dependent text, see section 6>
```
There is no whitespace, newline or padding between regions. A reader must not
skip optional characters.
---
## 5. Configuration record
The configuration is a JSON object encoded as UTF-8, with no line breaks.
Keys are sorted; separators are `,` and `:` with no surrounding spaces. The
canonical form is therefore deterministic: the same configuration always
renders as the same octets.
### 5.1 Required fields
A configuration missing any of these is invalid, and the artefact must be
rejected rather than partially interpreted.
| Field | Type | Meaning |
|---|---|---|
| `kind` | string | `"ciphertext"` or `"key"` |
| `v` | integer | Format version; `1` for this specification |
| `mode` | string | Performance mode, see §5.2 |
| `mid` | string | Intermediate representation, see §5.3 |
| `out` | string | Output encoding, see §5.4 |
| `alg` | string | Algorithm family; `"chaoscrypt"` |
| `kdf` | string | Keystream derivation, see §5.5 |
| `keybits` | integer | Length of the long key in bits |
| `ksum` | string | Non-secret key digest, see §5.6 |
### 5.2 `mode`
| Value | Pipeline |
|---|---|
| `reference` | Original algorithm, character pipeline |
| `fast` | Original algorithm, bulk-operation implementation |
| `turbo` | SHAKE256 keystream, byte pipeline |
| `raw` | SHAKE256 keystream, byte pipeline with the long-key layer retained |
`reference` and `fast` produce identical ciphertexts. The distinction is
recorded so a reader can report which implementation wrote the artefact; it
does not affect decryption.
### 5.3 `mid` — intermediate representation
The `mid` field names how the two XOR layers of the byte pipeline exchange
their data. It is only meaningful for `turbo` and `raw`; for the character
pipelines it is descriptive.
| Value | Meaning |
|---|---|
| `bt` | Intermediate values carried as raw bytes (default) |
| `hex` | Intermediate values carried as hexadecimal text |
`turbo` and `raw` accept either value, and `bt` is the default. The choice is
recorded in the header and honoured when the artefact is read: a `turbo` or
`raw` artefact is decrypted with the `mid` it carries, and no fallback to the
other representation is attempted.
`reference` and `fast` are character pipelines and always use `hex`. They
ignore `mid`: whatever value is supplied, the header records `hex` for them.
**Expansion.** `bt` passes the bytes between the XOR layers unchanged, so the
only growth is the output encoding: 2.00x with `hex` output, 1.33x with
`base` output. `hex` re-encodes each layer's output as hexadecimal text
before the next layer consumes it; with the two layers of this format that
doubles the payload at each layer, so the byte payload handed to the output
encoder is about **4x** the `bt` size (roughly 8 hexadecimal characters per
input octet with `hex` output).
**Speed.** `bt` is about **4x faster** than `hex`: it skips the per-layer hex
encode and decode and XORs the shorter byte buffers directly. It is therefore
the default.
### 5.4 `out` — output encoding
| Value | Meaning | Expansion |
|---|---|---|
| `hex` | Two characters per octet | 2.00x |
| `base` | Base64, four characters per three octets | 1.33x |
`reference` and `fast` always emit `hex` and ignore any attempt to set it.
`turbo` and `raw` accept either.
> **Reader requirement.** The payload must be decoded according to `out`.
> Attempting to decode with the wrong encoding must fail, never silently produce
> a different result.
### 5.5 `kdf` — keystream derivation
| Value | Meaning |
|---|---|
| `expand` | Hand-rolled mixing and rotation expansion |
| `shake256` | SHAKE256 extensible-output function |
### 5.6 `ksum` — key digest
A 16-character lowercase hexadecimal string: the first 16 characters of
`SHA256(upper_mapping ‖ lower_mapping ‖ long_key ‖ short_key)`, where `‖` is
concatenation of the ASCII encodings.
It exists so a reader can confirm that a key file and a ciphertext belong
together without exposing any usable secret. It is a **correlation aid, not a
security control**: it reveals nothing that helps an attacker, and its absence
of secrecy must not be relied upon as an integrity guarantee.
### 5.7 Legacy fields
Two optional fields exist for reading artefacts produced before the header was
introduced. They are never written by the current library except when wrapping a
legacy artefact, and they are **not** part of :data:`REQUIRED_FIELDS`.
| Field | Type | Meaning |
|---|---|---|
| `is_old` | boolean | The artefact predates this format |
| `old_is_key` | boolean | With `is_old`, whether it is a key file (`true`) or a ciphertext (`false`) |
> **Precedence rule.** When `is_old` is present and true, **every other field is
> ignored**, including `mode`, `mid`, `out` and `kind`. The artefact predates the
> field set, so there is nothing else meaningful to read. A reader must not
> reject such an artefact for missing `kind`, nor act on any field beside
> `is_old` and `old_is_key`.
An artefact that carries neither field is a normal artefact and is read
normally. Their absence is not an error.
### 5.8 Descriptive fields
The record also carries fields that describe the construction. They are
informational — a reader may use them for display or diagnostics — and they do
not modify the decryption path.
| Field | Meaning |
|---|---|
| `lib` | Library version that wrote the artefact |
| `cache` | Keystream cache strategy in effect; does not affect output |
| `subst` | Substitution kind, `"bijective"` |
| `flip` | Case-flip kind, `"conditional"` |
| `order` | The pipeline, as an ordered list of stage names |
| `xor_layers` | Number of XOR layers applied |
| `compact` | Whether the byte pipeline was used |
| `keyshort` | Length of the short key in bits |
| `flipbits` | Number of bits in the flip pattern |
| `b64` | Whether Base64 is used as a byte-safety layer |
| `utf8` | Whether text is transported as UTF-8 |
### 5.9 Example
```json
{
"alg": "chaoscrypt",
"b64": true,
"cache": "hash",
"compact": true,
"flip": "conditional",
"flipbits": 10,
"kdf": "shake256",
"keybits": 16384,
"keyshort": 2048,
"kind": "ciphertext",
"ksum": "3f9a1c7e5b2d4086",
"lib": "4.2.6",
"mid": "bt",
"mode": "turbo",
"order": "base64>subst>flip>reverse>xor>xor",
"out": "hex",
"subst": "bijective",
"utf8": true,
"v": 1,
"xor_layers": 2
}
```
Rendered between the markers, this is a single unbroken line.
---
## 6. Payload
### 6.1 Ciphertext payload
When `kind` is `"ciphertext"`, the payload is the ciphertext encoded per `out`:
- `out = "hex"`: lowercase hexadecimal, even length, alphabet `[0-9a-f]`.
- `out = "base"`: standard Base64 with `=` padding, alphabet
`[A-Za-z0-9+/]`.
The payload is the final output of the pipeline named in `mode`. Nothing is
appended after it.
### 6.2 Key payload
When `kind` is `"key"`, the payload is the password-wrapped key material, in the
same two encodings.
A caller reading a key file must check that `kind` is `"key"`. A key file is not
a ciphertext and must not be accepted where a ciphertext is expected, nor the
reverse. This is enforced, not advisory.
---
## 7. Reader conformance
A conforming reader performs these steps, in order, and fails at the first
that does not hold. It must not attempt recovery, interpretation or fallback.
| # | Check | Failure |
|---|---|---|
| 1 | Input is non-empty | `E017` |
| 2 | Input starts with `69CES` | `E017` |
| 3 | The 64 characters after the magic equal the begin marker | `E018` |
| 4 | The end marker occurs after the begin marker | `E018` |
| 5 | Text between the markers is valid UTF-8 JSON | `E018` |
| 6 | That JSON is an object | `E018` |
| 7 | Every required field of §5.1 is present | `E018` |
| 8 | `kind`, `mid` and `out` hold permitted values | `E018` |
| 9 | `kind` matches what the caller asked for | `E018` |
| 10 | The payload decodes under `out` | `E010` |
| 11 | Decryption succeeds under `mode` and the key | `E011` |
### 7.1 No fallback
There is no lenient path. An artefact without a header is not a ChaosCrypt
artefact and is rejected with `E017`. Artefacts written by revisions before the
header existed are not read by this path either: they are recovered only
through the explicit compatibility API, which wraps them in a header first
(see section 12). The ordinary reader never gains a lenient branch.
### 7.2 No partial trust
A header is either wholly valid or wholly rejected. A reader must not act on
fields it did manage to parse, because a partially parsed header may describe a
different construction than the one that produced the payload.
---
## 8. Error codes
| Code | Name | Raised when |
|---|---|---|
| `E010` | `MalformedCiphertext` | Payload does not decode under `out` |
| `E011` | `DecryptionFailed` | Decryption produced invalid data |
| `E017` | `MissingMagicHeader` | No magic present; input is not a CES artefact |
| `E018` | `MalformedHeader` | Marker missing, JSON invalid, field absent or out of range, or `kind` mismatch |
Codes `E001`–`E016` cover key handling, argument and I/O failures and are
unchanged.
---
## 9. Versioning
`v` is the format version and is independent of the library version in `lib`.
A reader must reject an artefact whose `v` it does not implement, with `E018`.
Adding optional descriptive fields does not change `v`. Changing the magic, the
markers, the region order, or the meaning of a required field does, and requires
a new major library release.
---
## 10. Conformance checklist
An implementation claims conformance when it:
- [ ] writes the magic, both markers and the configuration in the order of §4;
- [ ] sorts configuration keys and uses `,` and `:` as separators with no spaces;
- [ ] includes every required field of §5.1;
- [ ] rejects input without the magic with `E017`;
- [ ] rejects malformed headers with `E018`, never partially trusting them;
- [ ] enforces the `kind` match on both read and write paths;
- [ ] decodes the payload strictly under `out`, failing rather than guessing;
- [ ] implements no lenient or legacy fallback path.
---
---
## 11. Worked examples
### 11.1 A normal ciphertext
Text that is encrypted in `turbo` with `base64` output, then the layout read
back region by region.
```python
from chaoscrypt import ChaosCrypt
cc = ChaosCrypt(mode="turbo", encoding="base64")
cc.load("my.key", "key-file-password")
token = cc.encrypt("meet me at the usual place", "encryption-password")
```
The token begins with the five magic octets, then the begin marker:
```
69CES
385aeff1f4179a744c8fb0c5ae4702d325f6230d059f4251135c2536409dee93
```
then the configuration, which states the parameters actually used:
```json
{"alg":"chaoscrypt","b64":true,"cache":"hash","compact":true,
"flip":"conditional","flipbits":10,"kdf":"shake256","keybits":16384,
"keyshort":2048,"kind":"ciphertext","ksum":"8007e271aea2b261",
"lib":"4.2.6","mid":"bt","mode":"turbo",
"order":"base64>subst>flip>reverse>xor>xor","out":"base","subst":"bijective",
"utf8":true,"v":1,"xor_layers":2}
```
then the end marker, then the base64 payload:
```
2025ea4e4b4b93803f2ccadeaf318d1957ce42ff5409410f660348be96a4c0f2
IUhCQ0RFRkdISUpLTE1OT1BRUlNUVVZXWFla...
```
Decrypting needs no configuration at all — the record supplies it:
```python
from chaoscrypt import ChaosCrypt
from chaoscrypt._header import read_header, strip_header
cfg = read_header(token)
print(cfg["mode"], cfg["out"]) # turbo base
# a fresh instance with no settings reads it correctly
plain = ChaosCrypt(key_file="my.key", key_password="key-file-password",
auto_load=True).decrypt(token, "encryption-password")
```
### 11.2 Reading an artefact without knowing anything about it
Because the header is complete, a reader needs only the key file and the
password. The mode, the intermediate representation and the output encoding are
all taken from the artefact.
```python
from chaoscrypt import ChaosCrypt
cc = ChaosCrypt(key_file="my.key", key_password="key-file-password",
auto_load=True)
cc.load("my.key", "key-file-password")
# whatever produced this, it will be read correctly
plain = cc.decrypt(open("message.ces").read(), "encryption-password")
```
### 11.3 Inspecting a key file
```python
from chaoscrypt._header import read_header, strip_header
text = open("my.key", encoding="utf-8").read()
cfg = read_header(text)
print(cfg["kind"]) # key
print(cfg["alg"]) # chaoscrypt
print(cfg["keybits"]) # 16384
print(cfg["ksum"]) # 16 hex characters
```
`ksum` lets a caller confirm that a key file and a ciphertext belong together
without exposing anything usable:
```python
cs = open("message.ces", encoding="utf-8").read()
assert read_header(cs)["ksum"] == read_header(text)["ksum"], "wrong key file"
```
### 11.4 A rejection
```python
from chaoscrypt import ChaosCrypt
from chaoscrypt.errors import ChaosCryptError
cc = ChaosCrypt(key_file="my.key", key_password="key-file-password",
auto_load=True)
try:
cc.decrypt("7a3f9c...", "encryption-password") # a bare payload
except ChaosCryptError as e:
print(e.code) # E017
print(e.detail) # MissingMagicHeader
```
There is no fallback path here. The input is not a CES artefact, and guessing
would risk returning garbage that looks like success.
---
## 12. Legacy artefacts
Artefacts written before this format existed have no header. They are handled by
**wrapping**, never by loosening the reader.
### 12.1 What a legacy artefact looks like
| Kind | Content |
|---|---|
| Legacy ciphertext | Hexadecimal text, no prefix of any kind |
| Legacy key file | Password-wrapped key material, no prefix of any kind |
Neither carries a magic value, a marker or a configuration record.
### 12.2 Wrapping
To read one, a minimal header is synthesised and prefixed. The payload is not
touched.
```json
{"is_old":true,"old_is_key":false}
```
That header is a normal, valid header. Wrapping therefore produces an artefact
that the ordinary path can read, and **the ordinary path never gains a lenient
branch**: it still rejects headerless input with `E017`.
```python
from chaoscrypt import ChaosCrypt
cc = ChaosCrypt(key_file="my.key", key_password="key-file-password",
auto_load=True)
# a legacy ciphertext: no header
plain = cc.decrypt_legacy("72370655031311011c111f261365172716020b69",
"encryption-password")
```
`decrypt_legacy` first tries the input as it stands. If that reports a missing
header, it wraps the input and tries again. `decrypt_legacy_auto` additionally
probes whether the artefact is a key file or a ciphertext, so the caller does
not have to say which.
A legacy key file is loaded the same way:
```python
legacy_text = open("old-encryption.key", encoding="utf-8").read()
cc = ChaosCrypt()
cc.load_legacy_keys(legacy_text, "key-file-password")
```
Or wrapped explicitly, when the artefact is to be stored in the new form:
```python
modernised = cc.wrap_legacy(legacy_text, is_key=True)
open("my.key", "w", encoding="utf-8").write(modernised)
```
### 12.3 Which algorithm reads a legacy artefact
`is_old` is true, so every other field is ignored — there is no `mode` to
consult. The legacy path tries the bulk-operation implementation first and
falls back to the original character pipeline:
| Attempt | Why |
|---|---|
| 1. `fast` | Same algorithm, faster; correct for anything the bulk path can read |
| 2. `reference` | The original pipeline, in case the artefact needs it |
Both implement the original algorithm, so either can read pre-header material.
The fallback costs a second attempt only when the first fails.
### 12.4 What is not supported
- **Writing legacy artefacts.** The library only reads them. Output always
carries a header.
- **Partial trust of a legacy artefact.** It is wrapped whole; nothing is
inferred from its content.
- **Reading a legacy artefact without wrapping.** The ordinary path will reject
it with `E017`. Use the compatibility API.
### 12.5 Conformance for readers
An implementation that supports legacy artefacts must:
- [ ] detect a headerless input and treat it as legacy, not as an error at the
API boundary;
- [ ] synthesise a header rather than bypass the parser;
- [ ] ignore every field except `is_old` and `old_is_key` when `is_old` is true;
- [ ] keep the ordinary path strict — a headerless input passed to `decrypt`
still raises `E017`;
- [ ] never write a legacy artefact.
---
## 13. Relation to the cipher
The header is metadata. It does not add secrecy, and it is not authenticated.
An attacker who modifies the header can cause a decryption to fail, which is a
denial of service and no more — the payload cannot be recovered without the key.
Where an application needs to detect tampering with the header as well as the
payload, it must compute a MAC over the **entire artefact**, header included,
and verify that MAC before parsing. The format does not do this for you.
See [SECURITY.md](../SECURITY.md) for what the cipher guarantees and what it
does not.
+5
View File
@@ -7,6 +7,7 @@ Reference material for ChaosCrypt.
| [API.md](API.md) | Complete Python API reference |
| [CLI.md](CLI.md) | Command line reference, pipelines, troubleshooting |
| [ARCHITECTURE.md](ARCHITECTURE.md) | Module map, data flow, design decisions |
| [benchmark.md](benchmark.md) | Performance measurements and mode comparison |
| [BUILDING.md](BUILDING.md) | Building, testing and releasing |
| [../SECURITY.md](../SECURITY.md) | Design, key space, threat model, attack analysis |
| [../README.md](../README.md) | Project overview and quick start |
@@ -26,6 +27,10 @@ Read the [Scope](../README.md#scope) section of the README, then
**Using the command line**
[CLI.md](CLI.md) — covers every subcommand, plus pipelines and shell aliases.
**Choosing a performance mode**
[benchmark.md](benchmark.md) for the numbers, [SECURITY.md §4](../SECURITY.md)
for what each mode costs in cryptographic margin.
**Understanding how it works**
[ARCHITECTURE.md](ARCHITECTURE.md) for the code structure, and
[SECURITY.md §3](../SECURITY.md) for the algorithm itself.
+251
View File
@@ -0,0 +1,251 @@
# Benchmark
Performance reference for `chaoscrypt` **4.2.6**.
> **Read this first.** These numbers are not a claim that ChaosCrypt competes
> with a C-backed cipher. It is pure Python. AES-GCM in `cryptography` runs at
> hundreds of megabytes per second; ChaosCrypt's fastest mode manages tens.
> What the tables below show is what the implementation costs, how the modes
> differ, and which parameters are realistic for the workloads this library is
> meant for.
---
## 1. Headline figures
`raw` mode, hex output, keystream cache warm, best of several runs.
| Payload | `bt` encrypt | `bt` decrypt | `hex` encrypt | `hex` decrypt |
|---|---:|---:|---:|---:|
| 64 KiB | 26.9 | 60.6 | 20.7 | 20.2 |
| 128 KiB | 54.9 | 85.5 | 15.8 | 14.3 |
| 1 MiB | 57.3 | 61.0 | 19.3 | 21.8 |
| 16 MiB | 63.4 | 69.0 | 18.9 | 22.7 |
| 128 MiB | 59.4 | 64.5 | 18.2 | 18.0 |
| 1024 MiB | 47.9 | 31.7 | — | — |
MB/s. Ciphertext expansion: `bt` **2.00x**, `hex` **8.00x**.
**The one-line summary:** `raw` with the default `bt` intermediate runs at
roughly **60 MB/s encryption and 70 MB/s decryption**, with ciphertext twice the
payload size. Throughput holds steady across four orders of magnitude, which is
what a linear algorithm looks like.
### Against the original implementation
| | Original | `raw` bt | Improvement |
|---|---:|---:|---:|
| 1 MiB encrypt | 12.050 s (0.08 MB/s) | 0.017 s (57 MB/s) | **≈700x** |
| Ciphertext | 5.33x | 2.00x | 62% smaller |
---
## 2. Test environment
| Item | Value |
|---|---|
| CPU | 16 logical cores |
| Python | CPython 3.13.4 |
| OS | Windows 10 (10.0.26200) |
| Library | `chaoscrypt` 4.2.6, pure Python, zero dependencies |
| Payload | ASCII, `"A" * n` |
| Measurement | Best of several runs; each size warmed once so the keystream cache is populated |
Best-of-N is used because the machine is not otherwise idle. That makes the
figures optimistic; a loaded system will be slower, and the ordering between
modes is unaffected.
> **1024 MiB with `hex`** needs an 8 GB ciphertext as a single Python string,
> which is not addressable. That cell is left blank rather than measured in a
> way that would only report the allocator's behaviour.
---
## 3. Throughput across four orders of magnitude
`raw`, `bt` intermediate, encryption:
| Size | MB/s | Ratio to previous |
|---|---:|---:|
| 64 KiB | 26.9 | — |
| 128 KiB | 54.9 | 2.04x |
| 1 MiB | 57.3 | 1.04x |
| 16 MiB | 63.4 | 1.11x |
| 128 MiB | 59.4 | 0.94x |
| 1024 MiB | 47.9 | 0.81x |
From 128 KiB upward the figure is flat within ±15%, which is measurement noise
plus cache effects rather than algorithmic behaviour. **64 KiB reads low
because fixed setup costs are a larger share of a short operation**, not because
something is quadratic.
The 1024 MiB figure is lower because a 2 GB ciphertext string puts the process
under memory pressure. It is an observation about the machine, not the
algorithm.
### The quadratic bug that used to be here
An earlier revision was genuinely super-linear, and it showed up exactly this
way: throughput fell as payload grew. The cause was `_get_dynamic_key`:
```python
key = self.long_key
while len(key) < text_length:
key += self.long_key # reallocates the whole accumulator every round
```
Covering a 5.6 MB intermediate took **866 ms**. Multiplication instead:
```python
return (lk * (text_length // ll + 1))[:text_length]
```
The same work takes **3 ms**, with byte-identical output. `_expand_keystream_slow`
shared the pattern and was fixed the same way.
---
## 4. Intermediate representation
The setting with the largest effect on both speed and size.
| Payload | `bt` enc | `bt` dec | `hex` enc | `hex` dec | Ciphertext `bt` / `hex` |
|---|---:|---:|---:|---:|---:|
| 64 KiB | 26.9 | 60.6 | 20.7 | 20.2 | 0.1 / 0.5 MB |
| 1 MiB | 57.3 | 61.0 | 19.3 | 21.8 | 2 / 8 MB |
| 16 MiB | 63.4 | 69.0 | 18.9 | 22.7 | 32 / 128 MB |
| 128 MiB | 59.4 | 64.5 | 18.2 | 18.0 | 256 / 1024 MB |
`hex` is about **3x slower** and produces **4x more** ciphertext. It re-encodes
the payload between the XOR layers, which doubles it twice. It exists for
interoperability with the character pipeline's shape, not for performance.
---
## 5. Output encoding
| Encoding | Expansion | Notes |
|---|---:|---|
| `hex` | 2.00x | Two characters per octet |
| `base64` | 1.33x | Four characters per three octets |
Base64 produces a third less output at broadly the same speed. The choice
affects only the final encode.
---
## 6. How the modes compare
| | `reference` | `fast` | `turbo` | `raw` |
|---|---|---|---|---|
| 1 MiB encrypt | 12.05 s | 0.35 s | 0.05 s | 0.017 s |
| Ciphertext | 5.33x | 5.33x | 2.00x | 2.00x |
| Payload compatible with pre-4.2.6 | yes | yes | no | no |
| Keystream primitive | hand-rolled expansion | hand-rolled expansion | SHAKE256 | SHAKE256 |
`fast` is `reference` with the same arithmetic performed by C-level bulk
operations; its payload is byte-identical. The frozen vectors assert this, so
the equivalence cannot silently stop holding.
`turbo` and `raw` replace the keystream derivation with SHAKE256 and stop
re-encoding between layers. `raw` keeps the long-key XOR layer, `turbo` does not.
---
## 7. Where the time goes
Profiling `raw` with the `bt` intermediate, 10 MiB payload, encryption:
| Stage | Time | Share |
|---|---:|---:|
| `_bytes_stages` (substitution, flip, reversal) | 29 ms | 24% |
| XOR with the long key | 38 ms | 32% |
| XOR with the SHAKE keystream | 38 ms | 32% |
| Keystream derivation (cached) | ~0 ms | 0% |
| Output encode (`.hex()`) | 9 ms | 8% |
| **Total** | **119 ms** | |
Decryption is the mirror image, at 122 ms, and is if anything slightly quicker
end to end because it does not encode its output.
### The changes that mattered
**1. Keeping the payload in bytes between XOR layers (4x).**
The original re-encoded to hexadecimal after each XOR, doubling the payload at
every layer. At 1 MiB that meant a 5.6 MB intermediate. Bytes between layers
means a 1.4 MB intermediate instead.
**2. Per-character loops to `bytes.translate` (61x on substitution alone).**
Substitution was a dictionary lookup per character; it is now one translation
over a 256-entry table. The case flip is periodic, so it became ten strided
slice translations instead of a per-character branch.
**3. Per-byte XOR to one big-integer XOR (43x).**
```python
# before
for i, char in enumerate(text):
result.append(f"{ord(char) ^ ord(key[i % key_len]):02x}")
# after
xored = int.from_bytes(data, 'big') ^ int.from_bytes(key, 'big')
return xored.to_bytes(n, 'big').hex()
```
**4. Not copying or scanning the whole artefact on decrypt (2x).**
The decrypt path used to call `strip()`, then `int(payload, 16)`, and
`strip_header` sliced the whole string three times. On a 20 MB artefact that was
about 65 ms of pure copying. Removing it took decryption at 512 KiB from
34 MB/s to 87 MB/s.
---
## 8. What did not work
An attempt to build all expansion chunks with `numpy` as a two-dimensional
array reached only 2.9x and added a dependency. Cached translation tables were
faster and dependency-free.
A later attempt to fold the hex round trip in `_derive_final_key` by processing
only the prefix the output consumes gained 1.6x — worth keeping, but far less
than the byte-pipeline change that made the whole stage cheaper.
---
## 9. Reproducing these numbers
```bash
python bench/benchmark.py
python bench/benchmark.py --sizes 64,1024,65536 --budget 0.05 --repeats 3
python bench/benchmark.py --groups Text,Binary
```
The harness dispatches every task to a process pool, one worker per core, and
reports the best of N rounds per task.
### A note on large payloads
Beyond roughly 128 MiB the ciphertext itself becomes the practical limit: at
1024 MiB inputs, `bt` needs a 2 GB string and `hex` needs 8 GB. For payloads
that large, encrypt in blocks. The per-block throughput is the same, as §3
shows.
---
## 10. Summary
| Dimension | Result |
|---|---|
| Fastest throughput | **~63 MB/s encryption, ~85 MB/s decryption** (`raw`, `bt`, hex) |
| Ciphertext overhead | 2.00x (`bt`) or 1.33x (`base64`) |
| Speed with a payload compatible with pre-4.2.6 | `fast`, ~30x the original |
| Linear across | 64 KiB to 1 GiB |
| Dependencies | none, in every mode |
| Best suited for | Notes, credentials, documents, personal backups |
| Not suited for | Bulk media at gigabyte scale, high-throughput services, KDF stretching |
> **Bottom line.** The original implementation's cost was almost entirely
> Python-level per-byte work, not the cipher's arithmetic. Keeping the payload
> in bytes between the XOR layers removed the largest remaining factor, and the
> result is a library that runs at tens of megabytes per second rather than
> fractions of one — with the same construction, and with the modes and their
> trade-offs documented in [SECURITY.md](../SECURITY.md).
+12 -1
View File
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
[project]
name = "chaoscrypt"
version = "2.1.6"
version = "4.2.6"
description = "A chaos-based obfuscation cipher with a bilingual TUI, a full CLI and a clean Python API."
readme = "README.md"
requires-python = ">=3.8"
@@ -93,8 +93,19 @@ chaoscrypt = "chaoscrypt.cli:cli_main"
# ---------------------------------------------------------------------------
[tool.setuptools]
py-modules = []
# Listed module by module. Automatic discovery would pick up chaoscrypt.tests,
# which has an __init__.py and would otherwise be installed as part of the
# package; the development directories must stay in the source tree only.
packages = ["chaoscrypt"]
[tool.setuptools.exclude-package-data]
chaoscrypt = [
"tests/*",
"examples/*",
"legacy/*",
]
[tool.setuptools.package-data]
chaoscrypt = ["py.typed"]