Compare commits
2
Commits
017972d8b4
...
main
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
dd49043171 | ||
|
|
24a36d6fb4 |
+163
-75
@@ -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
|
Self-describing artefacts, a byte pipeline worth using, and a large performance
|
||||||
restructures the project as a distributable library and brings the
|
pass. This release changes the on-disk format incompatibly and is the first
|
||||||
documentation in line with it.
|
version intended to be deployed rather than experimented with.
|
||||||
|
|
||||||
### Added
|
### Added
|
||||||
|
|
||||||
- **Bilingual interactive TUI.** A menu-driven interface with English and
|
- **Self-describing header on every artefact.** Each key file and ciphertext now
|
||||||
Chinese, switchable at runtime. Uses `getpass` for password entry on a
|
begins with a magic value, two fixed markers, and a complete JSON
|
||||||
terminal and degrades to plain input when piped, so it remains scriptable.
|
configuration record that states how the payload was produced. A reader never
|
||||||
- **Full command line interface.** Subcommands `keygen`, `encrypt`, `decrypt`,
|
has to be told the mode, the encoding or the intermediate representation: it
|
||||||
`file`, `info`, `chpwd` and `tui`, with `--json` output, stdin/stdout
|
reads them. See [docs/FORMAT.md](docs/FORMAT.md).
|
||||||
piping, and three ways to supply each password (inline, environment
|
|
||||||
variable, password file).
|
```
|
||||||
- **Unified error hierarchy.** Sixteen named error types, all subclasses of
|
69CES
|
||||||
`ChaosCryptError`, each rendering as `ChaosCrypt_ERR_<Detail>_<Code>`. Every
|
385aeff1f4179a744c8fb0c5ae4702d325f6230d059f4251135c2536409dee93
|
||||||
failure path in the library now raises rather than returning a sentinel.
|
{"alg":"chaoscrypt","kind":"ciphertext","mode":"turbo","out":"hex",...}
|
||||||
- **Binary and file support.** `encrypt_bytes` / `decrypt_bytes` for arbitrary
|
2025ea4e4b4b93803f2ccadeaf318d1957ce42ff5409410f660348be96a4c0f2
|
||||||
binary data, and `encrypt_file` / `decrypt_file` for whole files.
|
<payload>
|
||||||
- **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.
|
- **Two new error codes**, for the two ways a header can be wrong:
|
||||||
- **Comprehensive documentation.** `SECURITY.md` presents the design, key
|
- `E017 MissingMagicHeader` — the input is not a CES artefact at all
|
||||||
space derivation, threat model and attack analysis in full. `docs/`
|
- `E018 MalformedHeader` — a marker is missing, the JSON is unusable, a
|
||||||
contains API, CLI and architecture references.
|
required field is absent, or `kind` does not match
|
||||||
- **Test suite.** Round-trip integrity, binary safety, key management, error
|
|
||||||
types, CLI behaviour, TUI interaction, internationalisation, and
|
- **Byte pipeline for `turbo` and `raw`.** Between the XOR layers the payload is
|
||||||
bidirectional interoperability with the original implementation.
|
now carried as raw bytes rather than hexadecimal text. This removes a
|
||||||
- **Packaging.** `pyproject.toml`, `MANIFEST.in`, `.gitignore`, `py.typed`,
|
doubling of the payload at each layer: expansion drops from **5.33x to 2.00x**
|
||||||
runnable examples, and MIT licensing.
|
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
|
### Changed
|
||||||
|
|
||||||
- **Project restructured** into a standard library layout. The importable
|
- **Default mode is `fast`**, which is byte-for-byte compatible with the
|
||||||
package now lives at `chaoscrypt/`, with tests, examples and the legacy
|
original algorithm and roughly 30x quicker.
|
||||||
implementation alongside it, and documentation and build artefacts at the
|
|
||||||
repository root.
|
- **Substitution, case flipping and the printable fold** run through
|
||||||
- **Code comments unified in English**, and public docstrings expanded to
|
`bytes.translate` over precomputed 256-entry tables.
|
||||||
document parameters, return values and raised errors.
|
|
||||||
- **English is now the default UI language**, with Chinese available as an
|
- **XOR layers** use a single big-integer operation instead of a per-byte loop
|
||||||
alternative.
|
with `%02x` formatting.
|
||||||
- **Packaging metadata** updated for the new layout and SPDX licence
|
|
||||||
expression.
|
- **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
|
### Fixed
|
||||||
|
|
||||||
Six defects found and corrected during the restructure:
|
1. Key material derivation is no longer quadratic. `_get_dynamic_key` was the
|
||||||
|
worst offender, and `_expand_keystream_slow` shared the pattern.
|
||||||
1. The `-p` and `-P` option groups both registered `--pwd`, causing an
|
2. Two hex-intermediate pipelines were asymmetric, so a `turbo` or `raw`
|
||||||
`argparse` conflict that prevented the CLI from starting at all.
|
artefact produced with `mid="hex"` could not be read back. Both are now
|
||||||
2. An incorrect key file password was reported as a corrupted file (`E002`)
|
exact mirrors.
|
||||||
rather than a credential error (`E003`). A structural validation step now
|
3. `change_key_password` and `export_key_text` wrote artefacts without a header,
|
||||||
distinguishes the two cases.
|
producing files this library then refused to load.
|
||||||
3. `export_key_text` produced key material without loading it into the
|
4. The constructor accepted `encoding="base64"` while the header records
|
||||||
instance, so the returned key could not be used directly.
|
`out="base"`. Both spellings are now accepted, so a caller can read a header
|
||||||
4. **Non-hexadecimal input was accepted as ciphertext and silently decrypted
|
and pass the value straight back in.
|
||||||
into garbage.** This was the most serious defect: a corrupt or truncated
|
5. A payload that is not valid hexadecimal now reports `E010`
|
||||||
ciphertext was indistinguishable from a successful decryption. Malformed
|
(MalformedCiphertext) rather than `E011` (DecryptionFailed). The distinction
|
||||||
input now raises `E010` before any processing occurs.
|
matters: the first means the artefact is malformed, the second means the
|
||||||
5. The TUI failed outright under piped input, because `getpass` requires a
|
password or key is wrong.
|
||||||
TTY. It now detects this and falls back to plain input.
|
6. The TUI's encoding menu referenced a missing translation and displayed the
|
||||||
6. After generating a key file, the TUI continued to look at the default file
|
key name instead of the description.
|
||||||
name rather than the one just created. The key file is now remembered for
|
|
||||||
the rest of the session.
|
|
||||||
|
|
||||||
### Security
|
### Security
|
||||||
|
|
||||||
- Clearly documented that ChaosCrypt is unaudited and non-standardised, and
|
- **Format break from pre-4.2.6 artefacts.** Headerless input is rejected with
|
||||||
that it is intended for obfuscation, personal use, and research or teaching
|
`E017`; use the compatibility API to read old material. Old scripts cannot
|
||||||
rather than production deployment.
|
read new artefacts. This is deliberate and documented, not an oversight.
|
||||||
- Documented the deterministic-output property and its consequences, and the
|
- **`fast` is not a weaker mode**: it performs the same arithmetic and produces
|
||||||
information disclosed by ciphertext length and Base64 padding class.
|
the same bytes. The test suite asserts this against the frozen vectors.
|
||||||
- Documented the strength of the construction in full, including the
|
- **`raw` with a hex intermediate is the weakest configuration** and is
|
||||||
approximately 10^5621 key space, the absence of algebraic and
|
documented as such: fewer structural layers stand between an attacker and the
|
||||||
number-theoretic structure, and the effect of Shor's and Grover's
|
substituted text.
|
||||||
algorithms.
|
- 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
|
### Compatibility
|
||||||
|
|
||||||
Fully backward compatible with the original single-file implementation, in
|
- `reference` and `fast` produce payloads byte-for-byte identical to the
|
||||||
both directions:
|
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
|
## [2.1.6] — 2026-09-27
|
||||||
file format is unchanged.
|
|
||||||
|
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
|
### Added
|
||||||
|
|
||||||
- Random system key generation: independent uppercase and lowercase
|
- Random system key generation.
|
||||||
bijections, digit and padding substitutions, a 10-bit case-flip pattern, a
|
|
||||||
4096-nibble long key and a 512-nibble short key.
|
|
||||||
- Password-protected key file wrapping.
|
- Password-protected key file wrapping.
|
||||||
- Layered encryption: Base64 encoding, substitution, conditional case
|
- Layered encryption: Base64, substitution, conditional case flipping,
|
||||||
flipping, whole-message reversal, and two XOR stages.
|
whole-message reversal, and two XOR stages.
|
||||||
- Interactive menu for encryption, decryption and key management.
|
- 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.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
|
[2.0.0]: https://git.dvscloud.net/dvs/ChaosCrypt/releases/tag/v2.0.0
|
||||||
|
|||||||
+11
-6
@@ -1,25 +1,30 @@
|
|||||||
# Files included in the source distribution.
|
# Files included in the source distribution.
|
||||||
#
|
#
|
||||||
# Note: the development directories (tests/, examples/, legacy/) are
|
# The development directories (tests/, examples/, legacy/) sit inside the
|
||||||
# deliberately NOT listed here. They sit inside the package directory in the
|
# package directory in the source tree. They are covered below so the sdist
|
||||||
# source tree, and MANIFEST.in entries under a package path are treated as
|
# carries them, but they must never reach the wheel: the explicit `packages`
|
||||||
# package data, which would place them in the wheel as well. The source tree
|
# list in pyproject.toml keeps them out.
|
||||||
# itself is the distribution for development purposes; the sdist carries the
|
|
||||||
# library and its documentation.
|
|
||||||
|
|
||||||
include README.md
|
include README.md
|
||||||
include LICENSE
|
include LICENSE
|
||||||
include SECURITY.md
|
include SECURITY.md
|
||||||
include CHANGELOG.md
|
include CHANGELOG.md
|
||||||
include pyproject.toml
|
include pyproject.toml
|
||||||
|
include setup.py
|
||||||
include .gitignore
|
include .gitignore
|
||||||
|
|
||||||
recursive-include docs *.md
|
recursive-include docs *.md
|
||||||
|
recursive-include bench *.py
|
||||||
|
|
||||||
# The installable package.
|
# The installable package.
|
||||||
include chaoscrypt/*.py
|
include chaoscrypt/*.py
|
||||||
include chaoscrypt/py.typed
|
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 *.py[cod]
|
||||||
global-exclude __pycache__/*
|
global-exclude __pycache__/*
|
||||||
global-exclude .DS_Store
|
global-exclude .DS_Store
|
||||||
|
|||||||
@@ -1,6 +1,7 @@
|
|||||||
# ChaosCrypt
|
# 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.**
|
||||||
|
|
||||||
[](https://www.python.org/)
|
[](https://www.python.org/)
|
||||||
[](LICENSE)
|
[](LICENSE)
|
||||||
@@ -22,66 +23,119 @@ purposes:
|
|||||||
**If you need standardised cryptography, use a standardised cipher.** AES-GCM
|
**If you need standardised cryptography, use a standardised cipher.** AES-GCM
|
||||||
or ChaCha20-Poly1305 from a vetted library such as
|
or ChaCha20-Poly1305 from a vetted library such as
|
||||||
[`cryptography`](https://cryptography.io) are the right tools for production
|
[`cryptography`](https://cryptography.io) are the right tools for production
|
||||||
systems, regulated data, and long-lived secrets. ChaosCrypt is not a
|
systems, regulated data, and long-lived secrets.
|
||||||
replacement for them and does not claim to be.
|
|
||||||
|
|
||||||
See [SECURITY.md](SECURITY.md) for the complete design description, key-space
|
See [SECURITY.md](SECURITY.md) for the full design and threat analysis, and
|
||||||
derivation, and attack analysis.
|
[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.
|
Each key file and ciphertext begins with a header that states how it was made.
|
||||||
ChaosCrypt is deliberately built to remove every kind of structure that
|
A reader never has to be told the mode, the encoding, or anything else — it
|
||||||
classical cryptanalysis relies on, and the result is a design with real
|
reads them from the artefact.
|
||||||
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.**
|
|
||||||
|
|
||||||
```
|
```
|
||||||
plaintext
|
69CES
|
||||||
| Base64 lift arbitrary bytes into printable ASCII
|
385aeff1f4179a744c8fb0c5ae4702d325f6230d059f4251135c2536409dee93
|
||||||
| substitution destroy frequency structure
|
{"alg":"chaoscrypt","kind":"ciphertext","mode":"turbo","out":"hex","mid":"bt",...}
|
||||||
| conditional case flip remove linearity
|
2025ea4e4b4b93803f2ccadeaf318d1957ce42ff5409410f660348be96a4c0f2
|
||||||
| whole-message reversal destroy locality
|
<payload>
|
||||||
| XOR with long key erase residual substituted structure
|
|
||||||
| XOR with derived key sever any link to the key file alone
|
|
||||||
ciphertext
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**No algebraic structure to attack.** The substitution tables are arbitrary
|
The consequence is deliberate: **input without a valid header is rejected**
|
||||||
permutations stored as data, so there is no polynomial representation.
|
(`E017`), rather than guessed at. A ciphertext decrypted under the wrong
|
||||||
Differential, linear and algebraic cryptanalysis all require a compact
|
parameters produces garbage that looks like a wrong password, and the header
|
||||||
algebraic description that simply does not exist here.
|
removes that ambiguity entirely.
|
||||||
|
|
||||||
**No number-theoretic structure either.** There is no modular arithmetic, no
|
```python
|
||||||
group operation and no lattice, so Shor's algorithm has nothing to solve.
|
from chaoscrypt import ChaosCrypt
|
||||||
Grover's algorithm reduces the search to about 10^2810 — still far beyond any
|
|
||||||
physically realisable computation.
|
|
||||||
|
|
||||||
**The two XOR layers shield each other.** An attacker who recovers the outer
|
cc = ChaosCrypt(key_file="my.key", key_password="key-file-password",
|
||||||
keystream still faces the 4096-nibble long key, and no keystream recovered
|
auto_load=True)
|
||||||
from one message is reusable against another, because the derivation is
|
|
||||||
parameterised by message length.
|
|
||||||
|
|
||||||
**Lossless for arbitrary binary data.** Every stage is a bijection, so images,
|
# whatever produced this, it will be read correctly
|
||||||
archives and database dumps round-trip byte-for-byte. Verified in the test
|
plain = cc.decrypt(open("message.ces").read(), "encryption-password")
|
||||||
suite from 0 to 100,000 bytes, including NUL bytes and invalid UTF-8.
|
```
|
||||||
|
|
||||||
**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
|
## Performance modes
|
||||||
complete argument-driven CLI for automation, and a typed Python API for
|
|
||||||
embedding — all three backed by the same sixteen-code error hierarchy.
|
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
|
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.
|
**Requires** Python 3.8 or newer. No third-party runtime dependencies.
|
||||||
|
|
||||||
---
|
---
|
||||||
@@ -111,130 +157,69 @@ pip install .
|
|||||||
from chaoscrypt import ChaosCrypt
|
from chaoscrypt import ChaosCrypt
|
||||||
|
|
||||||
cc = ChaosCrypt()
|
cc = ChaosCrypt()
|
||||||
|
|
||||||
# Generate a key file once, then keep it somewhere safe.
|
|
||||||
cc.create_key("key-file-password", "my.key")
|
cc.create_key("key-file-password", "my.key")
|
||||||
|
|
||||||
# Encrypt and decrypt.
|
|
||||||
token = cc.encrypt("hello world", "encryption-password")
|
token = cc.encrypt("hello world", "encryption-password")
|
||||||
assert cc.decrypt(token, "encryption-password") == "hello world"
|
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:
|
Binary data and files:
|
||||||
|
|
||||||
```python
|
```python
|
||||||
from chaoscrypt import ChaosCrypt
|
cc = ChaosCrypt("my.key", "key-file-password", auto_load=True)
|
||||||
|
|
||||||
cc = ChaosCrypt("my.key", "key-file-pwd", auto_load=True)
|
|
||||||
|
|
||||||
raw = open("photo.png", "rb").read()
|
raw = open("photo.png", "rb").read()
|
||||||
ct = cc.encrypt_bytes(raw, "encryption-password")
|
open("photo.cc", "w").write(cc.encrypt_bytes(raw, "encryption-password"))
|
||||||
open("photo.cc", "w").write(ct)
|
|
||||||
|
|
||||||
restored = cc.decrypt_bytes(ct, "encryption-password")
|
cc.encrypt_file("photo.png", "encryption-password") # -> photo.png.cc
|
||||||
open("photo.restored.png", "wb").write(restored)
|
cc.decrypt_file("photo.png.cc", "encryption-password") # -> photo.png
|
||||||
|
|
||||||
# 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
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**Error handling.** Every failure is a subclass of `ChaosCryptError` and
|
Error handling — every failure is a `ChaosCryptError` and renders as
|
||||||
renders as `ChaosCrypt_ERR_<Detail>_<Code>`:
|
`ChaosCrypt_ERR_<Detail>_<Code>`:
|
||||||
|
|
||||||
```python
|
```python
|
||||||
from chaoscrypt import ChaosCrypt, ChaosCryptError
|
from chaoscrypt import ChaosCrypt, ChaosCryptError
|
||||||
|
|
||||||
cc = ChaosCrypt()
|
|
||||||
try:
|
try:
|
||||||
cc.load("my.key", "wrong-password")
|
ChaosCrypt().load("my.key", "wrong-password")
|
||||||
except ChaosCryptError as e:
|
except ChaosCryptError as e:
|
||||||
print(e) # ChaosCrypt_ERR_KeyPasswordIncorrect_E003
|
print(e) # ChaosCrypt_ERR_KeyPasswordIncorrect_E003
|
||||||
print(e.code) # E003
|
print(e.code) # E003
|
||||||
print(e.detail) # KeyPasswordIncorrect
|
|
||||||
```
|
```
|
||||||
|
|
||||||
Catching `ChaosCryptError` handles everything the library can raise.
|
|
||||||
|
|
||||||
### 2. As a command line tool
|
### 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
|
```bash
|
||||||
chaoscrypt
|
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
|
[*] Key file loaded my.key [fast]
|
||||||
obfuscation, personal use and study -- not for production systems.
|
|
||||||
|
|
||||||
[ ] No key loaded yet. [encryption.key]
|
|
||||||
|
|
||||||
------------------------------------------------------------------
|
------------------------------------------------------------------
|
||||||
Select an action
|
Select an action
|
||||||
@@ -248,136 +233,57 @@ obfuscation, personal use and study -- not for production systems.
|
|||||||
[7] Show key information
|
[7] Show key information
|
||||||
[8] Change key file password
|
[8] Change key file password
|
||||||
[9] Switch language
|
[9] Switch language
|
||||||
|
[m] Performance mode
|
||||||
|
[e] Output encoding
|
||||||
[a] About / security notice
|
[a] About / security notice
|
||||||
[q] Quit
|
[q] Quit
|
||||||
------------------------------------------------------------------
|
------------------------------------------------------------------
|
||||||
```
|
```
|
||||||
|
|
||||||
- **Bilingual**: option `[9]` switches between English and Chinese at runtime,
|
Bilingual (option `[9]`), passwords are not echoed, and the interface degrades
|
||||||
and every label follows.
|
cleanly when output is piped.
|
||||||
- **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.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## The two-password model
|
## Error codes
|
||||||
|
|
||||||
ChaosCrypt separates the secret that protects the key file from the secret
|
| Code | Meaning |
|
||||||
used for each message. Keeping them distinct is what makes key rotation cheap:
|
|---|---|
|
||||||
|
| `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 |
|
Codes are stable and safe to branch on.
|
||||||
|---|---|---|
|
|
||||||
| **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.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## How it works
|
## Documentation
|
||||||
|
|
||||||
```
|
| Document | Contents |
|
||||||
plaintext P
|
|---|---|
|
||||||
|
|
| [SECURITY.md](SECURITY.md) | Design, key space, threat model, attack analysis |
|
||||||
+-- Base64 encode -----------------> printable ASCII
|
| [docs/FORMAT.md](docs/FORMAT.md) | **Normative format specification**, with examples |
|
||||||
|
|
| [docs/benchmark.md](docs/benchmark.md) | Measured throughput and the profiling behind it |
|
||||||
+-- Letter substitution -----------> two independent 26! bijections
|
| [docs/API.md](docs/API.md) | Complete Python API reference |
|
||||||
|
|
| [docs/CLI.md](docs/CLI.md) | Command line reference and troubleshooting |
|
||||||
+-- Conditional case flip ---------> 10-bit pattern, adds non-linearity
|
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Internal design and module map |
|
||||||
|
|
| [docs/BUILDING.md](docs/BUILDING.md) | Building, testing and releasing |
|
||||||
+-- Whole-message reversal --------> destroys local correlation
|
| [CHANGELOG.md](CHANGELOG.md) | Release history |
|
||||||
|
|
|
||||||
+-- 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>
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -395,39 +301,28 @@ twine check dist/* # validate package metadata
|
|||||||
```
|
```
|
||||||
ChaosCrypt/
|
ChaosCrypt/
|
||||||
├── README.md SECURITY.md LICENSE CHANGELOG.md
|
├── README.md SECURITY.md LICENSE CHANGELOG.md
|
||||||
├── docs/ additional documentation
|
├── docs/
|
||||||
├── pyproject.toml
|
├── pyproject.toml
|
||||||
├── dist/ build artefacts
|
├── dist/
|
||||||
└── chaoscrypt/ source tree
|
└── chaoscrypt/
|
||||||
├── __init__.py public API and the ChaosCrypt facade
|
├── __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
|
├── cli.py argument-driven command line interface
|
||||||
├── tui.py interactive bilingual interface
|
├── tui.py interactive bilingual interface
|
||||||
├── errors.py the unified error hierarchy
|
├── errors.py the unified error hierarchy
|
||||||
├── i18n.py UI strings
|
├── i18n.py UI strings
|
||||||
├── tests/ test suite
|
├── tests/ test suite, including frozen vectors
|
||||||
├── examples/ runnable examples
|
├── 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
|
## Licence
|
||||||
|
|
||||||
[MIT](LICENSE) — provided as-is, without warranty of any kind.
|
[MIT](LICENSE) — provided as-is, without warranty of any kind.
|
||||||
|
|
||||||
ChaosCrypt has not been independently audited. It is intended for
|
ChaosCrypt has not been independently audited. It is intended for obfuscation,
|
||||||
obfuscation, personal use, and research or teaching. Do not deploy it where
|
personal use, and research or teaching. Do not deploy it where an audited,
|
||||||
an audited, standardised cryptographic primitive is required.
|
standardised cryptographic primitive is required.
|
||||||
|
|||||||
+522
-171
@@ -1,10 +1,10 @@
|
|||||||
# Security Policy
|
# 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 |
|
| **Status** | Unaudited, non-standardised construction |
|
||||||
| **Intended use** | Obfuscation · personal use · research and teaching |
|
| **Intended use** | Obfuscation · personal use · research and teaching |
|
||||||
| **Licence** | MIT |
|
| **Licence** | MIT |
|
||||||
@@ -14,22 +14,23 @@
|
|||||||
## 1. Scope of this document
|
## 1. Scope of this document
|
||||||
|
|
||||||
This policy describes what ChaosCrypt is designed to do, what it is explicitly
|
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
|
not designed to do, and how it behaves under each class of attack a reviewer is
|
||||||
reviewer is likely to consider.
|
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
|
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
|
appropriate for a given task. The answer is a straightforward one, and it comes
|
||||||
given first:
|
first:
|
||||||
|
|
||||||
> **If you need standardised cryptography, use a standardised cipher.**
|
> **If you need standardised cryptography, use a standardised cipher.**
|
||||||
> Use AES-GCM or ChaCha20-Poly1305 from a vetted library such as
|
> Use AES-GCM or ChaCha20-Poly1305 from a vetted library such as
|
||||||
> [`cryptography`](https://cryptography.io). Those constructions are
|
> [`cryptography`](https://cryptography.io). Those constructions are analysed,
|
||||||
> analysed, standardised, and widely deployed; ChaosCrypt is none of these.
|
> standardised, and widely deployed; ChaosCrypt is none of these.
|
||||||
|
|
||||||
ChaosCrypt exists for the cases where a standard cipher is not the point:
|
ChaosCrypt exists for the cases where a standard cipher is not the point: making
|
||||||
making data unreadable to casual inspection, protecting your own notes and
|
data unreadable to casual inspection, protecting your own notes and backups with
|
||||||
backups with something you can read end to end, and studying how layered
|
something you can read end to end, and studying how layered obfuscation behaves
|
||||||
obfuscation behaves in practice.
|
in practice.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -51,8 +52,8 @@ obfuscation behaves in practice.
|
|||||||
| Long-lived secrets (10+ year horizon) | **No** | Standardised primitives age far better |
|
| Long-lived secrets (10+ year horizon) | **No** | Standardised primitives age far better |
|
||||||
| Safety-critical or medical systems | **No** | Requires formal verification |
|
| Safety-critical or medical systems | **No** | Requires formal verification |
|
||||||
|
|
||||||
The dividing line is not "how secret is the data" but "what does a failure
|
The dividing line is not "how secret is the data" but "what does a failure cost,
|
||||||
cost, and who has to sign off on it". Personal notes and internal drafts sit
|
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
|
comfortably on the left of that line. Anything with a regulator, an auditor or
|
||||||
a liability attached sits on the right.
|
a liability attached sits on the right.
|
||||||
|
|
||||||
@@ -60,10 +61,10 @@ a liability attached sits on the right.
|
|||||||
|
|
||||||
## 3. What ChaosCrypt is
|
## 3. What ChaosCrypt is
|
||||||
|
|
||||||
ChaosCrypt is a **layered obfuscation cipher**. Its design premise is to
|
ChaosCrypt is a **layered obfuscation cipher**. Its design premise is to replace
|
||||||
replace algebraic structure with randomness, so that an attacker's only
|
algebraic structure with randomness, so that an attacker's only realistic path is
|
||||||
realistic path is exhaustive search — and that path is then pushed beyond what
|
exhaustive search — and that path is then pushed beyond what is physically
|
||||||
is physically reachable.
|
reachable.
|
||||||
|
|
||||||
### 3.1 Definition
|
### 3.1 Definition
|
||||||
|
|
||||||
@@ -81,7 +82,7 @@ Let:
|
|||||||
- `F ∈ {0,1}^10` is the case-flip pattern
|
- `F ∈ {0,1}^10` is the case-flip pattern
|
||||||
- `K_user` be the user-supplied encryption password
|
- `K_user` be the user-supplied encryption password
|
||||||
|
|
||||||
Encryption is then:
|
Encryption in the **`reference`** mode is:
|
||||||
|
|
||||||
```
|
```
|
||||||
E(P, K_sys, K_user) = XorFinal(
|
E(P, K_sys, K_user) = XorFinal(
|
||||||
@@ -101,16 +102,16 @@ E(P, K_sys, K_user) = XorFinal(
|
|||||||
where:
|
where:
|
||||||
|
|
||||||
- **`Substitution(B, U, L, D, E)`** maps each character of `B` through `U`,
|
- **`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
|
`L` or `D` depending on its class. Each `=` in `B` is removed and the padding
|
||||||
padding count is encoded via `E` into a trailing marker.
|
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`
|
- **`Flip(s, F)`** swaps the case of the *i*-th character when `F[i mod 10] = 1`
|
||||||
and that character is a letter.
|
and that character is a letter.
|
||||||
- **`Reverse(s)`** reverses the whole string.
|
- **`Reverse(s)`** reverses the whole string.
|
||||||
- **`XorDynamic(s, K_long)`** XORs `s` against `K_long`, emitting hexadecimal.
|
- **`XorDynamic(s, K_long)`** XORs `s` against `K_long`, emitting hexadecimal.
|
||||||
- **`DeriveKey(K_user, K_short, n)`** mixes the password with the short key
|
- **`DeriveKey(K_user, K_short, n)`** mixes the password with the short key
|
||||||
through alternating interleaving, bit operations, grouped permutation and
|
through alternating interleaving, bit operations, grouped permutation and
|
||||||
reversal, then extends the result to length `n` using three rotating
|
reversal, then extends the result to length `n` using three rotating expansion
|
||||||
expansion modes.
|
modes.
|
||||||
- **`XorFinal(s, K)`** XORs `s` against `DeriveKey(..., |s|)`.
|
- **`XorFinal(s, K)`** XORs `s` against `DeriveKey(..., |s|)`.
|
||||||
|
|
||||||
Decryption is the exact inverse of each step, applied in reverse order.
|
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**:
|
The encryption path is lossless for **arbitrary byte sequences**:
|
||||||
|
|
||||||
@@ -146,21 +232,24 @@ arbitrary bytes P
|
|||||||
→ reversal (permutation over positions)
|
→ reversal (permutation over positions)
|
||||||
→ XOR with K_long (bijective over the character space)
|
→ XOR with K_long (bijective over the character space)
|
||||||
→ XOR with derived key (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
|
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
|
bijection. Base64 encoding is the only stage that changes the representation of
|
||||||
of the data, and it is exactly invertible. Decryption therefore recovers `P`
|
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
|
byte-for-byte, whether the input was text, an image, an archive or a database
|
||||||
database dump.
|
dump.
|
||||||
|
|
||||||
This is verified in the test suite for sizes from 0 to 100 000 bytes,
|
`raw` follows the same argument with the Base64 stage moved to the end and the
|
||||||
including inputs containing NUL bytes and invalid UTF-8 sequences.
|
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
|
The components are generated independently, so the composite space is their
|
||||||
product:
|
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
|
≈ 10^5621
|
||||||
```
|
```
|
||||||
|
|
||||||
`K_user` is chosen by the user and is therefore not part of this count; it is
|
`K_user` is chosen by the user and is therefore not part of this count; it is an
|
||||||
an independent factor on top.
|
independent factor on top.
|
||||||
|
|
||||||
For scale:
|
For scale:
|
||||||
|
|
||||||
@@ -201,7 +290,7 @@ For scale:
|
|||||||
| AES-256 key space | `≈ 10^77` |
|
| AES-256 key space | `≈ 10^77` |
|
||||||
| RSA-2048 modulus space | `≈ 10^617` |
|
| 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
|
Exhaustive search requires on average `S/2 ≈ 10^5621` attempts. At an assumed
|
||||||
global ceiling of `10^18` attempts per second:
|
global ceiling of `10^18` attempts per second:
|
||||||
@@ -212,69 +301,120 @@ Age of the universe ≈ 10^18 seconds
|
|||||||
T / age ≈ 10^5585
|
T / age ≈ 10^5585
|
||||||
```
|
```
|
||||||
|
|
||||||
Exhaustive search is not merely impractical; it is outside the physical
|
Exhaustive search is not merely impractical; it is outside the physical budget
|
||||||
budget of the universe by an enormous margin.
|
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
|
### 7.1 What the header is for
|
||||||
printable-ASCII intermediates. It carries:
|
|
||||||
|
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;
|
- a uniform byte distribution, with no statistical bias to exploit;
|
||||||
- no periodicity, since the effective keystream length is at least the
|
- no periodicity, since the effective keystream length is at least the message
|
||||||
message length;
|
length;
|
||||||
- no structural markers, since the internal separators are consumed by the
|
- no structural markers, since the internal separators are consumed by the XOR
|
||||||
XOR layers before output.
|
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.**
|
**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
|
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
|
recover the keystream for that session. Three properties limit the damage:
|
||||||
properties limit the damage:
|
|
||||||
|
|
||||||
1. `n` is the message length, so **each distinct length yields a distinct
|
1. **The keystream is bound to the message length.** In `reference` and `fast`
|
||||||
keystream**. Recovering one does not enable decryption of another.
|
the derivation is parameterised by `n = |P|`; in `turbo` and `raw` the length
|
||||||
2. `K_stream` is the *output* of a non-invertible mixing pipeline; recovering
|
is hashed into the SHAKE256 seed. Two messages of different lengths therefore
|
||||||
it does not yield `K_user` or `K_short`.
|
yield unrelated keystreams, and recovering one does not enable decryption of
|
||||||
3. The inner XOR layer still requires `K_long`, which is independent.
|
another.
|
||||||
|
2. **The keystream is not invertible.** In `reference`/`fast` it is the output
|
||||||
Recovering `K_long` requires the inner 4096-nibble key, which is itself
|
of a non-invertible mixing pipeline; in `turbo`/`raw` it is the output of a
|
||||||
protected by the outer layer. The two layers are mutually shielding.
|
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
|
**Known-plaintext attack does not recover any key component**, and does not
|
||||||
produce a keystream reusable against other messages.
|
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
|
An attacker submitting crafted plaintexts can, in principle, determine the
|
||||||
substitution tables `U`, `L`, `D` and `E` by observing how each character class
|
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
|
is mapped — the tables are static for a given key file.
|
||||||
across messages for a given key file.
|
|
||||||
|
|
||||||
Determining the tables does **not** yield:
|
Determining the tables does **not** yield:
|
||||||
|
|
||||||
- `K_long` — it is only ever combined by XOR and never directly exposed;
|
- `K_long` — only ever combined by XOR, never directly exposed;
|
||||||
- `K_short` — it enters only via `DeriveKey`, whose output is not invertible;
|
- `K_short` — enters only through the keystream derivation and the SHAKE seed;
|
||||||
- `K_user` — supplied per-session and never materialised in the ciphertext.
|
- `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
|
Once the tables are known, the attacker still faces an XOR layer keyed by 4096
|
||||||
4096 nibbles plus a derived keystream. **Chosen-plaintext attack does not
|
nibbles plus a derived keystream. **Chosen-plaintext attack does not recover the
|
||||||
recover the full key.**
|
full key.**
|
||||||
|
|
||||||
### 6.4 Differential cryptanalysis
|
### 7.4 Differential cryptanalysis
|
||||||
|
|
||||||
A differential attack requires a probabilistic relationship between an input
|
A differential attack requires a probabilistic relationship between an input
|
||||||
difference and an output difference that holds with probability measurably
|
difference and an output difference that holds with probability measurably above
|
||||||
above chance.
|
chance.
|
||||||
|
|
||||||
The layers defeat this requirement individually:
|
|
||||||
|
|
||||||
- Substitution is a table lookup: a fixed input difference produces a fixed
|
- Substitution is a table lookup: a fixed input difference produces a fixed
|
||||||
output difference, with no exploitable propagation pattern.
|
output difference, with no exploitable propagation pattern.
|
||||||
@@ -282,132 +422,299 @@ The layers defeat this requirement individually:
|
|||||||
no algebraic description.
|
no algebraic description.
|
||||||
- Reversal maps the *i*-th position to the *(n−1−i)*-th, so positional
|
- Reversal maps the *i*-th position to the *(n−1−i)*-th, so positional
|
||||||
differences do not propagate coherently.
|
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.
|
There is no path from input difference to output difference with usable bias.
|
||||||
**Differential attack has no effective path.**
|
**Differential attack has no effective path.**
|
||||||
|
|
||||||
### 6.5 Linear cryptanalysis
|
### 7.5 Linear cryptanalysis
|
||||||
|
|
||||||
Linear cryptanalysis requires a linear approximation holding with bias
|
Linear cryptanalysis requires a linear approximation holding with bias different
|
||||||
different from 1/2.
|
from 1/2.
|
||||||
|
|
||||||
- Table-lookup substitution has no polynomial representation, so no linear
|
- Table-lookup substitution has no polynomial representation, so no linear
|
||||||
approximation can be constructed.
|
approximation can be constructed.
|
||||||
- The conditional flip is a branch, not a linear function.
|
- The conditional flip is a branch, not a linear function.
|
||||||
- The composition of two XOR layers with independent keystreams approaches
|
- The composition of two XOR layers with independent keystreams approaches zero
|
||||||
zero bias.
|
bias.
|
||||||
|
|
||||||
**Linear attack has no effective path.**
|
**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
|
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
|
solve it. The substitution tables have no algebraic representation: they are
|
||||||
representation: they are arbitrary permutations stored as data. No system of
|
arbitrary permutations stored as data. No system of equations can be written
|
||||||
equations can be written down without first recovering the tables themselves,
|
down without first recovering the tables themselves, which returns the problem
|
||||||
which returns the problem to §6.3.
|
to §7.3.
|
||||||
|
|
||||||
**Algebraic attack has no effective path.**
|
**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.
|
Structural attacks exploit symmetry or invariance in the round function.
|
||||||
ChaosCrypt has no round function, no symmetry, and no algebraic frame in which
|
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
|
invariance could be expressed. Related-key attacks require the key schedule to
|
||||||
treat related inputs similarly; here, different key files share no
|
treat related inputs similarly; here, different key files share no relationship,
|
||||||
relationship, and key material is drawn independently per component.
|
and key material is drawn independently per component.
|
||||||
|
|
||||||
**Structural and related-key attacks do not apply.**
|
**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
|
Shor's algorithm solves integer factorisation and discrete logarithm by
|
||||||
exploiting the number-theoretic structure of those problems. ChaosCrypt
|
exploiting the number-theoretic structure of those problems. ChaosCrypt contains
|
||||||
contains no number-theoretic structure: no modular arithmetic, no group
|
no number-theoretic structure: no modular arithmetic, no group operation, no
|
||||||
operation, no lattice. There is nothing for Shor's algorithm to solve.
|
lattice. There is nothing for Shor's algorithm to solve.
|
||||||
|
|
||||||
**Shor's algorithm does not apply.**
|
**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,
|
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
|
That remains far beyond any physically realisable computation. Even allowing for
|
||||||
for generous improvements in quantum hardware, a search space of that order
|
generous improvements in quantum hardware, a search space of that order is not
|
||||||
is not addressable.
|
addressable.
|
||||||
|
|
||||||
**Grover's algorithm applies in principle but changes nothing in practice.**
|
**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
|
Known quantum attacks target specific structures: finite fields, elliptic
|
||||||
curves, lattices, and hash function internals. ChaosCrypt contains none of
|
curves, lattices, and hash function internals. ChaosCrypt contains none of these.
|
||||||
these. No published quantum algorithm offers an advantage against it.
|
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
|
### 10.0 The three tiers
|
||||||
ChaosCrypt:
|
|
||||||
|
|
||||||
### 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
|
| Tier | Modes | Layers between ciphertext and substitution |
|
||||||
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*
|
| Most | `reference`, `fast` | XOR(long key) then XOR(derived keystream), both over hexadecimal text |
|
||||||
that you sent a 43-byte message is sensitive.
|
| 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
|
`raw` is the fastest mode by a wide margin — roughly nine times faster than
|
||||||
discloses `|P| mod 3`. This is two bits, strictly subsumed by §8.1, and
|
`fast` at 1 MiB, with ciphertext a quarter the size. It is also the weakest. This
|
||||||
reveals nothing about the key or contents.
|
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
|
### 9.1 Fewer layers
|
||||||
file. If you encrypt many messages under one key file, an attacker who
|
|
||||||
recovers the tables through chosen plaintexts (§6.3) narrows the remaining
|
`reference`, `fast` and `turbo` present an attacker with:
|
||||||
problem — though it remains infeasible. Rotating key files limits even this.
|
|
||||||
|
```
|
||||||
|
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
|
### 10.1 Message length
|
||||||
under the same key file and the same encryption password produces **the same
|
|
||||||
ciphertext**, byte for byte.
|
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
|
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
|
randomly generated per key file, and the initialisation role that an IV normally
|
||||||
normally plays is filled by the randomness of `K_sys`. Different key files
|
plays is filled by the randomness of `K_sys`. Different key files produce
|
||||||
produce entirely different ciphertexts, and a fresh key file is the
|
entirely different ciphertexts, and a fresh key file is the recommended way to
|
||||||
recommended way to obtain a fresh domain of randomness.
|
obtain a fresh domain of randomness.
|
||||||
|
|
||||||
The practical consequences:
|
The practical consequences:
|
||||||
|
|
||||||
- **Strength is unaffected.** Confidentiality does not depend on output
|
- **Strength is unaffected.** Confidentiality does not depend on output
|
||||||
variation.
|
variation.
|
||||||
- **Replay detection is your responsibility.** If two identical ciphertexts
|
- **Replay detection is your responsibility.** If two identical ciphertexts must
|
||||||
must be distinguishable, either use a fresh key file per session or add
|
be distinguishable, either use a fresh key file per session or add your own
|
||||||
your own nonce — for example a timestamp — to the plaintext before
|
nonce — a timestamp, for example — to the plaintext before encrypting, and
|
||||||
encrypting, and strip it after decryption.
|
strip it after decryption.
|
||||||
|
|
||||||
This is a design trade-off, documented here so that it is a decision rather
|
This is a design trade-off, documented here so that it is a decision rather than
|
||||||
than a surprise.
|
a surprise.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 10. Key derivation
|
## 14. Key derivation, per mode
|
||||||
|
|
||||||
|
### 12.1 `reference` and `fast`
|
||||||
|
|
||||||
`DeriveKey(K_user, K_short, n)` performs:
|
`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
|
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
|
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
|
In `fast` the same computation is performed with C-level bulk operations. The
|
||||||
style of PBKDF2, scrypt or Argon2, and it is not intended to be. The key file
|
output is identical; only the cost differs.
|
||||||
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
|
### 12.2 `turbo`
|
||||||
password here, choose a strong one anyway — the same advice applies to every
|
|
||||||
system that accepts a passphrase.
|
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."**
|
**"Known plaintext recovers the session keystream, which can then be reused."**
|
||||||
Recovering `K_stream` for one message does not help with another: the
|
Recovering a keystream for one message does not help with another: the keystream
|
||||||
keystream depends on the message length, and it cannot be inverted to
|
depends on the message length, and it cannot be inverted to `K_user` or
|
||||||
`K_user` or `K_short`. See §6.2.
|
`K_short`. See §7.2.
|
||||||
|
|
||||||
**"The expansion modes are public, so the keystream is predictable."**
|
**"The expansion modes are public, so the keystream is predictable."**
|
||||||
Knowing the algorithm is not knowing the input to it. The expansion operates
|
Knowing the algorithm is not knowing the input to it. The expansion operates on
|
||||||
on a seed derived from `K_user` and `K_short`, both unknown. This is the same
|
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.
|
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."**
|
**"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
|
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
|
fixed global secret but freshly generated per key file, so variation is supplied
|
||||||
supplied structurally. The genuine consequence is deterministic output, which
|
structurally. The genuine consequence is deterministic output, which is stated
|
||||||
is stated plainly in §9.
|
plainly in §11.
|
||||||
|
|
||||||
**"No standard KDF means the password is the weak point."**
|
**"No standard KDF means the password is the weak point."**
|
||||||
The password does not have to carry the full security burden: it is combined
|
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
|
with 512 nibbles of random key material from the key file. A weak password still
|
||||||
still degrades the composite, as it does everywhere else.
|
degrades the composite, as it does everywhere else.
|
||||||
|
|
||||||
**"Unaudited means broken."**
|
**"Unaudited means broken."**
|
||||||
Unaudited means unaudited. It describes what has and has not been checked,
|
Unaudited means unaudited. It describes what has and has not been checked, not
|
||||||
not what is or is not true. ChaosCrypt is offered with its analysis laid out
|
what is or is not true. ChaosCrypt is offered with its analysis laid out above
|
||||||
above so that you can evaluate it directly, and with a clear statement that
|
so that you can evaluate it directly, and with a clear statement that it should
|
||||||
it should not be relied on where certification is required.
|
not be relied on where certification is required.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 12. Summary
|
## 16. Summary
|
||||||
|
|
||||||
ChaosCrypt's security rests on a simple proposition: **replace algebraic
|
### Properties of the construction
|
||||||
structure with randomness, and place exhaustive search beyond physical
|
|
||||||
reach.**
|
|
||||||
|
|
||||||
Properties that follow from the construction:
|
|
||||||
|
|
||||||
- The composite key space is approximately `10^5621`.
|
- The composite key space is approximately `10^5621`.
|
||||||
- The construction admits no compact algebraic representation.
|
- The construction admits no compact algebraic representation.
|
||||||
@@ -477,40 +815,53 @@ Properties that follow from the construction:
|
|||||||
reusable keystream.
|
reusable keystream.
|
||||||
- Shor's algorithm does not apply; Grover's algorithm changes nothing that
|
- Shor's algorithm does not apply; Grover's algorithm changes nothing that
|
||||||
matters.
|
matters.
|
||||||
- Arbitrary binary data round-trips losslessly.
|
- Arbitrary binary data round-trips losslessly in every mode.
|
||||||
- There are no third-party runtime dependencies.
|
- There are no third-party runtime dependencies.
|
||||||
|
|
||||||
Properties to be aware of:
|
### Properties per mode
|
||||||
|
|
||||||
- Deterministic output for identical inputs (§9).
|
| Mode | Speed (1 MiB) | Ciphertext | Compatibility | Strength |
|
||||||
- Ciphertext length and `|P| mod 3` are observable (§8).
|
|---|---:|---:|---|---|
|
||||||
|
| `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.
|
- No independent audit has been performed.
|
||||||
|
|
||||||
**In one sentence:** ChaosCrypt is an obfuscation cipher with a strong
|
**In one sentence:** ChaosCrypt is an obfuscation cipher with a strong
|
||||||
construction and a deliberately narrow scope. It is well suited to protecting
|
construction and a deliberately narrow scope; its four modes trade speed against
|
||||||
your own data and to studying layered cipher design. It is not a substitute
|
structural margin, and the trade-offs are documented above rather than left for
|
||||||
for AES-GCM or ChaCha20-Poly1305, and it should not be deployed where an
|
you to discover.
|
||||||
audited, standardised primitive is required.
|
|
||||||
|
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
|
If you believe you have found a security issue in ChaosCrypt, please report it
|
||||||
privately before disclosing it publicly. Include:
|
privately before disclosing it publicly. Include:
|
||||||
|
|
||||||
- a description of the issue;
|
- a description of the issue;
|
||||||
- steps to reproduce, ideally with a minimal example;
|
- steps to reproduce, ideally with a minimal example;
|
||||||
- the version affected;
|
- the version and mode affected;
|
||||||
- any suggested remediation.
|
- any suggested remediation.
|
||||||
|
|
||||||
Reports are welcome and will be acknowledged. Note that ChaosCrypt is
|
Reports are welcome and will be acknowledged. Note that ChaosCrypt is maintained
|
||||||
maintained on a best-effort basis and comes with no warranty or support
|
on a best-effort basis and comes with no warranty or support commitment, as set
|
||||||
commitment, as set out in the MIT licence.
|
out in the MIT licence.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 14. Licence
|
## 18. Licence
|
||||||
|
|
||||||
MIT. Provided as-is, without warranty of any kind. The authors accept no
|
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
|
liability for any loss or damage arising from use of this software. See
|
||||||
|
|||||||
@@ -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
@@ -45,7 +45,24 @@ from __future__ import annotations
|
|||||||
import os
|
import os
|
||||||
from typing import Optional
|
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 (
|
from .errors import (
|
||||||
ChaosCryptError,
|
ChaosCryptError,
|
||||||
ChaosCrypt_ERR_KeyFileNotFound_E001,
|
ChaosCrypt_ERR_KeyFileNotFound_E001,
|
||||||
@@ -66,7 +83,7 @@ from .errors import (
|
|||||||
ChaosCrypt_ERR_UnsupportedKeyVersion_E016,
|
ChaosCrypt_ERR_UnsupportedKeyVersion_E016,
|
||||||
)
|
)
|
||||||
|
|
||||||
__version__ = "2.1.6"
|
__version__ = "4.2.6"
|
||||||
__author__ = "Dvs (DvsXT)"
|
__author__ = "Dvs (DvsXT)"
|
||||||
__license__ = "MIT"
|
__license__ = "MIT"
|
||||||
__all__ = [
|
__all__ = [
|
||||||
@@ -75,6 +92,20 @@ __all__ = [
|
|||||||
"__license__",
|
"__license__",
|
||||||
"DEFAULT_KEY_FILE",
|
"DEFAULT_KEY_FILE",
|
||||||
"KEYFILE_VERSION",
|
"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",
|
"ChaosCryptCore",
|
||||||
"ChaosCrypt",
|
"ChaosCrypt",
|
||||||
"ChaosCryptError",
|
"ChaosCryptError",
|
||||||
@@ -126,8 +157,11 @@ class ChaosCrypt:
|
|||||||
*,
|
*,
|
||||||
auto_load: bool = False,
|
auto_load: bool = False,
|
||||||
default_key_file: str = DEFAULT_KEY_FILE,
|
default_key_file: str = DEFAULT_KEY_FILE,
|
||||||
|
mode: str = DEFAULT_MODE,
|
||||||
|
encoding: str = DEFAULT_ENCODING,
|
||||||
|
mid: str = DEFAULT_MID,
|
||||||
) -> None:
|
) -> None:
|
||||||
self.core = ChaosCryptCore()
|
self.core = ChaosCryptCore(mode, encoding=encoding, mid=mid)
|
||||||
self.key_file = key_file
|
self.key_file = key_file
|
||||||
self.key_password = key_password
|
self.key_password = key_password
|
||||||
self.default_key_file = default_key_file
|
self.default_key_file = default_key_file
|
||||||
@@ -269,8 +303,12 @@ class ChaosCrypt:
|
|||||||
keys_data = self.core.generate_keymaterial()
|
keys_data = self.core.generate_keymaterial()
|
||||||
obfuscated = self.core._obfuscate_keys(keys_data)
|
obfuscated = self.core._obfuscate_keys(keys_data)
|
||||||
text = self.core._xor_encrypt_data(obfuscated, key_password)
|
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
|
self.key_password = key_password
|
||||||
return text
|
return document
|
||||||
|
|
||||||
def info(self) -> dict:
|
def info(self) -> dict:
|
||||||
"""Return a summary of the loaded key material.
|
"""Return a summary of the loaded key material.
|
||||||
@@ -336,12 +374,54 @@ class ChaosCrypt:
|
|||||||
}
|
}
|
||||||
obfuscated = self.core._obfuscate_keys(keys_data)
|
obfuscated = self.core._obfuscate_keys(keys_data)
|
||||||
encrypted = self.core._xor_encrypt_data(obfuscated, new_password)
|
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:
|
with open(target, 'w') as f:
|
||||||
f.write(encrypted)
|
f.write(document)
|
||||||
|
|
||||||
self.key_password = new_password
|
self.key_password = new_password
|
||||||
return target
|
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
|
# Encryption / decryption
|
||||||
# ==================================================================
|
# ==================================================================
|
||||||
|
|||||||
+1366
-207
File diff suppressed because it is too large
Load Diff
@@ -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
|
||||||
+95
-6
@@ -22,7 +22,8 @@ import os
|
|||||||
import sys
|
import sys
|
||||||
from typing import List, Optional
|
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
|
from .errors import ChaosCryptError, ChaosCrypt_ERR_InvalidArgument_E013
|
||||||
|
|
||||||
__all__ = ["build_parser", "main", "cli_main"]
|
__all__ = ["build_parser", "main", "cli_main"]
|
||||||
@@ -80,6 +81,42 @@ def _resolve_password(
|
|||||||
return None
|
return None
|
||||||
|
|
||||||
|
|
||||||
|
def _add_global_flags(parser: argparse.ArgumentParser) -> None:
|
||||||
|
"""Re-register the global output flags on a subcommand.
|
||||||
|
|
||||||
|
``--json`` and ``--quiet`` are also accepted before the subcommand. Adding
|
||||||
|
them here as well lets users write either form, which is what most people
|
||||||
|
reach for first::
|
||||||
|
|
||||||
|
chaoscrypt --json info -k my.key -P keypwd
|
||||||
|
chaoscrypt info -k my.key -P keypwd --json
|
||||||
|
|
||||||
|
The values are merged in :func:`main` by taking whichever was set.
|
||||||
|
"""
|
||||||
|
parser.add_argument(
|
||||||
|
"-j", "--json", action="store_true", default=False,
|
||||||
|
dest="json_local",
|
||||||
|
help="emit machine-readable JSON on stdout",
|
||||||
|
)
|
||||||
|
parser.add_argument(
|
||||||
|
"-q", "--quiet", action="store_true", default=False,
|
||||||
|
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(
|
def _add_password_opts(
|
||||||
parser: argparse.ArgumentParser,
|
parser: argparse.ArgumentParser,
|
||||||
prefix: str,
|
prefix: str,
|
||||||
@@ -155,6 +192,33 @@ def build_parser() -> argparse.ArgumentParser:
|
|||||||
"-q", "--quiet", action="store_true",
|
"-q", "--quiet", action="store_true",
|
||||||
help="suppress non-essential human-readable output",
|
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>")
|
sub = parser.add_subparsers(dest="command", metavar="<command>")
|
||||||
|
|
||||||
@@ -163,6 +227,7 @@ def build_parser() -> argparse.ArgumentParser:
|
|||||||
"keygen", help="generate a new key file",
|
"keygen", help="generate a new key file",
|
||||||
description="Generate a new ChaosCrypt key file.",
|
description="Generate a new ChaosCrypt key file.",
|
||||||
)
|
)
|
||||||
|
_add_global_flags(p_keygen)
|
||||||
p_keygen.add_argument(
|
p_keygen.add_argument(
|
||||||
"-k", "--key-file", default=DEFAULT_KEY_FILE, metavar="PATH",
|
"-k", "--key-file", default=DEFAULT_KEY_FILE, metavar="PATH",
|
||||||
help=f"output key file (default: {DEFAULT_KEY_FILE})",
|
help=f"output key file (default: {DEFAULT_KEY_FILE})",
|
||||||
@@ -179,6 +244,7 @@ def build_parser() -> argparse.ArgumentParser:
|
|||||||
"encrypt", help="encrypt text",
|
"encrypt", help="encrypt text",
|
||||||
description="Encrypt a string into a hexadecimal ciphertext.",
|
description="Encrypt a string into a hexadecimal ciphertext.",
|
||||||
)
|
)
|
||||||
|
_add_global_flags(p_enc)
|
||||||
p_enc.add_argument("text", nargs="?", help="plaintext (use - for stdin)")
|
p_enc.add_argument("text", nargs="?", help="plaintext (use - for stdin)")
|
||||||
p_enc.add_argument(
|
p_enc.add_argument(
|
||||||
"-i", "--in", dest="in_file", metavar="PATH",
|
"-i", "--in", dest="in_file", metavar="PATH",
|
||||||
@@ -202,6 +268,7 @@ def build_parser() -> argparse.ArgumentParser:
|
|||||||
"decrypt", help="decrypt text",
|
"decrypt", help="decrypt text",
|
||||||
description="Decrypt a hexadecimal ciphertext back into text.",
|
description="Decrypt a hexadecimal ciphertext back into text.",
|
||||||
)
|
)
|
||||||
|
_add_global_flags(p_dec)
|
||||||
p_dec.add_argument("text", nargs="?", help="ciphertext (use - for stdin)")
|
p_dec.add_argument("text", nargs="?", help="ciphertext (use - for stdin)")
|
||||||
p_dec.add_argument(
|
p_dec.add_argument(
|
||||||
"-i", "--in", dest="in_file", metavar="PATH",
|
"-i", "--in", dest="in_file", metavar="PATH",
|
||||||
@@ -228,6 +295,7 @@ def build_parser() -> argparse.ArgumentParser:
|
|||||||
file_sub = p_file.add_subparsers(dest="file_command", metavar="<action>")
|
file_sub = p_file.add_subparsers(dest="file_command", metavar="<action>")
|
||||||
|
|
||||||
p_fe = file_sub.add_parser("encrypt", help="encrypt a file to .cc")
|
p_fe = file_sub.add_parser("encrypt", help="encrypt a file to .cc")
|
||||||
|
_add_global_flags(p_fe)
|
||||||
p_fe.add_argument("src", help="source file")
|
p_fe.add_argument("src", help="source file")
|
||||||
p_fe.add_argument(
|
p_fe.add_argument(
|
||||||
"-o", "--out", dest="out_file", metavar="PATH",
|
"-o", "--out", dest="out_file", metavar="PATH",
|
||||||
@@ -240,6 +308,7 @@ def build_parser() -> argparse.ArgumentParser:
|
|||||||
dest_prefix="key_", long_prefix="key-pwd")
|
dest_prefix="key_", long_prefix="key-pwd")
|
||||||
|
|
||||||
p_fd = file_sub.add_parser("decrypt", help="decrypt a .cc file")
|
p_fd = file_sub.add_parser("decrypt", help="decrypt a .cc file")
|
||||||
|
_add_global_flags(p_fd)
|
||||||
p_fd.add_argument("src", help="source .cc file")
|
p_fd.add_argument("src", help="source .cc file")
|
||||||
p_fd.add_argument(
|
p_fd.add_argument(
|
||||||
"-o", "--out", dest="out_file", metavar="PATH",
|
"-o", "--out", dest="out_file", metavar="PATH",
|
||||||
@@ -257,6 +326,7 @@ def build_parser() -> argparse.ArgumentParser:
|
|||||||
description="Show metadata for a key file. Secret material is "
|
description="Show metadata for a key file. Secret material is "
|
||||||
"redacted unless --show-maps is given.",
|
"redacted unless --show-maps is given.",
|
||||||
)
|
)
|
||||||
|
_add_global_flags(p_info)
|
||||||
p_info.add_argument(
|
p_info.add_argument(
|
||||||
"-k", "--key-file", default=DEFAULT_KEY_FILE, metavar="PATH",
|
"-k", "--key-file", default=DEFAULT_KEY_FILE, metavar="PATH",
|
||||||
help=f"key file (default: {DEFAULT_KEY_FILE})",
|
help=f"key file (default: {DEFAULT_KEY_FILE})",
|
||||||
@@ -274,6 +344,7 @@ def build_parser() -> argparse.ArgumentParser:
|
|||||||
description="Re-wrap an existing key file under a new password. "
|
description="Re-wrap an existing key file under a new password. "
|
||||||
"The key material itself is unchanged.",
|
"The key material itself is unchanged.",
|
||||||
)
|
)
|
||||||
|
_add_global_flags(p_chpwd)
|
||||||
p_chpwd.add_argument(
|
p_chpwd.add_argument(
|
||||||
"-k", "--key-file", default=DEFAULT_KEY_FILE, metavar="PATH",
|
"-k", "--key-file", default=DEFAULT_KEY_FILE, metavar="PATH",
|
||||||
)
|
)
|
||||||
@@ -369,7 +440,7 @@ def _cmd_keygen(args: argparse.Namespace) -> int:
|
|||||||
args,
|
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)
|
path = cc.create_key(pwd, args.key_file, overwrite=args.force)
|
||||||
_emit(
|
_emit(
|
||||||
{"ok": True, "key_file": os.path.abspath(path)},
|
{"ok": True, "key_file": os.path.abspath(path)},
|
||||||
@@ -403,7 +474,7 @@ def _cmd_text(args: argparse.Namespace, mode: str) -> int:
|
|||||||
args.text, args.in_file, "plaintext" if mode == "encrypt" else "ciphertext"
|
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)
|
cc.load(args.key_file, key_pwd)
|
||||||
|
|
||||||
if mode == "encrypt":
|
if mode == "encrypt":
|
||||||
@@ -452,7 +523,7 @@ def _cmd_file(args: argparse.Namespace, mode: str) -> int:
|
|||||||
args,
|
args,
|
||||||
)
|
)
|
||||||
|
|
||||||
cc = ChaosCrypt()
|
cc = ChaosCrypt(mode=args.mode, encoding=args.encoding, mid=args.mid)
|
||||||
cc.load(args.key_file, key_pwd)
|
cc.load(args.key_file, key_pwd)
|
||||||
|
|
||||||
if mode == "encrypt":
|
if mode == "encrypt":
|
||||||
@@ -489,7 +560,7 @@ def _cmd_info(args: argparse.Namespace) -> int:
|
|||||||
args,
|
args,
|
||||||
)
|
)
|
||||||
|
|
||||||
cc = ChaosCrypt()
|
cc = ChaosCrypt(mode=args.mode, encoding=args.encoding, mid=args.mid)
|
||||||
cc.load(args.key_file, key_pwd)
|
cc.load(args.key_file, key_pwd)
|
||||||
info = cc.info()
|
info = cc.info()
|
||||||
|
|
||||||
@@ -529,7 +600,7 @@ def _cmd_chpwd(args: argparse.Namespace) -> int:
|
|||||||
args,
|
args,
|
||||||
)
|
)
|
||||||
|
|
||||||
cc = ChaosCrypt()
|
cc = ChaosCrypt(mode=args.mode, encoding=args.encoding, mid=args.mid)
|
||||||
path = cc.change_key_password(old, new, args.key_file)
|
path = cc.change_key_password(old, new, args.key_file)
|
||||||
_emit(
|
_emit(
|
||||||
{"ok": True, "key_file": os.path.abspath(path)},
|
{"ok": True, "key_file": os.path.abspath(path)},
|
||||||
@@ -557,6 +628,24 @@ def main(argv: Optional[List[str]] = None) -> int:
|
|||||||
parser = build_parser()
|
parser = build_parser()
|
||||||
args = parser.parse_args(raw)
|
args = parser.parse_args(raw)
|
||||||
|
|
||||||
|
# `--json` / `--quiet` are accepted both before and after the subcommand.
|
||||||
|
# The subparser writes to separate destinations so that an unset
|
||||||
|
# subcommand flag cannot clobber an explicitly set global one; the two are
|
||||||
|
# merged here.
|
||||||
|
args.json = bool(getattr(args, "json", False)
|
||||||
|
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":
|
if args.command is None or args.command == "tui":
|
||||||
from .tui import run_tui
|
from .tui import run_tui
|
||||||
return run_tui()
|
return run_tui()
|
||||||
|
|||||||
@@ -34,6 +34,8 @@ __all__ = [
|
|||||||
"ChaosCrypt_ERR_FileReadFailed_E014",
|
"ChaosCrypt_ERR_FileReadFailed_E014",
|
||||||
"ChaosCrypt_ERR_FileWriteFailed_E015",
|
"ChaosCrypt_ERR_FileWriteFailed_E015",
|
||||||
"ChaosCrypt_ERR_UnsupportedKeyVersion_E016",
|
"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",
|
"ChaosCrypt_ERR_UnsupportedKeyVersion_E016", "UnsupportedKeyVersion", "E016",
|
||||||
"The key file declares a format version this build cannot read.",
|
"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.",
|
||||||
|
)
|
||||||
|
|||||||
@@ -71,6 +71,45 @@ TEXTS: Dict[str, Dict[str, str]] = {
|
|||||||
"menu_keyinfo": {"en": "Show key information", "zh": "查看当前密钥信息"},
|
"menu_keyinfo": {"en": "Show key information", "zh": "查看当前密钥信息"},
|
||||||
"menu_chpwd": {"en": "Change key file password", "zh": "修改密钥文件密码"},
|
"menu_chpwd": {"en": "Change key file password", "zh": "修改密钥文件密码"},
|
||||||
"menu_lang": {"en": "Switch language", "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_about": {"en": "About / security notice", "zh": "关于 / 安全声明"},
|
||||||
"menu_quit": {"en": "Quit", "zh": "退出"},
|
"menu_quit": {"en": "Quit", "zh": "退出"},
|
||||||
"menu_prompt": {"en": "Enter option", "zh": "请输入选项编号"},
|
"menu_prompt": {"en": "Enter option", "zh": "请输入选项编号"},
|
||||||
|
|||||||
@@ -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")
|
||||||
|
)
|
||||||
@@ -73,8 +73,9 @@ class TestRoundTrip:
|
|||||||
ct = loaded.encrypt(text, USER_PWD)
|
ct = loaded.encrypt(text, USER_PWD)
|
||||||
assert loaded.decrypt(ct, USER_PWD) == text
|
assert loaded.decrypt(ct, USER_PWD) == text
|
||||||
|
|
||||||
def test_ciphertext_is_hex(self, loaded):
|
def test_ciphertext_payload_is_hex(self, loaded):
|
||||||
ct = loaded.encrypt("data", USER_PWD)
|
from chaoscrypt._header import strip_header
|
||||||
|
ct = strip_header(loaded.encrypt("data", USER_PWD))
|
||||||
int(ct, 16)
|
int(ct, 16)
|
||||||
|
|
||||||
def test_empty_plaintext_rejected(self, loaded):
|
def test_empty_plaintext_rejected(self, loaded):
|
||||||
@@ -98,21 +99,37 @@ class TestRoundTrip:
|
|||||||
b = loaded.encrypt("same", "pwd-B")
|
b = loaded.encrypt("same", "pwd-B")
|
||||||
assert a != 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:
|
with pytest.raises(ChaosCryptError) as ei:
|
||||||
loaded.decrypt("zzzz-not-hex", USER_PWD)
|
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:
|
with pytest.raises(ChaosCryptError) as ei:
|
||||||
loaded.decrypt("abc", USER_PWD)
|
loaded.decrypt("abc", USER_PWD)
|
||||||
assert ei.value.code == "E010"
|
assert ei.value.code == "E017"
|
||||||
|
|
||||||
def test_empty_ciphertext_rejected(self, loaded):
|
def test_empty_ciphertext_rejected(self, loaded):
|
||||||
with pytest.raises(ChaosCryptError) as ei:
|
with pytest.raises(ChaosCryptError) as ei:
|
||||||
loaded.decrypt("", USER_PWD)
|
loaded.decrypt("", USER_PWD)
|
||||||
assert ei.value.code == "E009"
|
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
|
# Binary
|
||||||
@@ -148,6 +165,33 @@ class TestKeyManagement:
|
|||||||
n.load(path, KEY_PWD)
|
n.load(path, KEY_PWD)
|
||||||
assert n.loaded
|
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):
|
def test_keygen_refuses_overwrite(self, tmp_path):
|
||||||
path = str(tmp_path / "k.key")
|
path = str(tmp_path / "k.key")
|
||||||
ChaosCrypt().create_key(KEY_PWD, path)
|
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")
|
path.write_text("this is not a chaoscrypt key file!!!", encoding="utf-8")
|
||||||
with pytest.raises(ChaosCryptError) as ei:
|
with pytest.raises(ChaosCryptError) as ei:
|
||||||
ChaosCrypt().load(str(path), KEY_PWD)
|
ChaosCrypt().load(str(path), KEY_PWD)
|
||||||
assert ei.value.code == "E002"
|
assert ei.value.code == "E017"
|
||||||
|
|
||||||
def test_load_empty_file(self, tmp_path):
|
def test_load_empty_file(self, tmp_path):
|
||||||
path = tmp_path / "empty.key"
|
path = tmp_path / "empty.key"
|
||||||
path.write_text("", encoding="utf-8")
|
path.write_text("", encoding="utf-8")
|
||||||
with pytest.raises(ChaosCryptError) as ei:
|
with pytest.raises(ChaosCryptError) as ei:
|
||||||
ChaosCrypt().load(str(path), KEY_PWD)
|
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):
|
def test_encrypt_without_key_raises(self):
|
||||||
cc = ChaosCrypt()
|
cc = ChaosCrypt()
|
||||||
@@ -223,10 +267,13 @@ class TestKeyManagement:
|
|||||||
assert len(info["flip_pattern"]) == 10
|
assert len(info["flip_pattern"]) == 10
|
||||||
|
|
||||||
def test_export_and_import_key_text(self):
|
def test_export_and_import_key_text(self):
|
||||||
|
from chaoscrypt._header import MAGIC, read_header
|
||||||
cc = ChaosCrypt()
|
cc = ChaosCrypt()
|
||||||
text = cc.export_key_text(KEY_PWD)
|
text = cc.export_key_text(KEY_PWD)
|
||||||
assert text and isinstance(text, str)
|
assert text and isinstance(text, str)
|
||||||
assert cc.loaded, "export_key_text should leave the instance usable"
|
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 = ChaosCrypt()
|
||||||
n.load_from_text(text, KEY_PWD)
|
n.load_from_text(text, KEY_PWD)
|
||||||
@@ -283,6 +330,13 @@ class TestFileAPI:
|
|||||||
back = loaded.decrypt_file(cc_file, USER_PWD, dst)
|
back = loaded.decrypt_file(cc_file, USER_PWD, dst)
|
||||||
assert open(back, "rb").read() == payload
|
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):
|
def test_default_suffixes(self, loaded, tmp_path):
|
||||||
src = tmp_path / "note.txt"
|
src = tmp_path / "note.txt"
|
||||||
src.write_text("hello file", encoding="utf-8")
|
src.write_text("hello file", encoding="utf-8")
|
||||||
@@ -351,9 +405,14 @@ class TestErrorClass:
|
|||||||
# ---------------------------------------------------------------------------
|
# ---------------------------------------------------------------------------
|
||||||
class TestLegacyCompatibility:
|
class TestLegacyCompatibility:
|
||||||
def test_format_matches_original_chain(self, loaded):
|
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"
|
text = "compat check compatibility"
|
||||||
ct = loaded.encrypt(text, USER_PWD)
|
ct = strip_header(loaded.encrypt(text, USER_PWD))
|
||||||
|
|
||||||
core = loaded.core
|
core = loaded.core
|
||||||
combined = core._xor_decrypt_with_final_key(ct, USER_PWD)
|
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
|
assert base64.b64decode((sub + "=" * eq_count).encode()).decode() == text
|
||||||
|
|
||||||
def test_keyfile_readable_by_original_scheme(self, keyfile):
|
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
|
_, path = keyfile
|
||||||
core = ChaosCryptCore()
|
core = ChaosCryptCore()
|
||||||
with open(path, "r") as f:
|
with open(path, "r") as f:
|
||||||
enc = f.read()
|
enc = strip_header(f.read())
|
||||||
|
|
||||||
decrypted = core._xor_decrypt_data(enc, KEY_PWD)
|
decrypted = core._xor_decrypt_data(enc, KEY_PWD)
|
||||||
assert decrypted is not None
|
assert decrypted is not None
|
||||||
@@ -462,9 +522,10 @@ class TestCLI:
|
|||||||
)
|
)
|
||||||
|
|
||||||
def test_version(self):
|
def test_version(self):
|
||||||
|
from chaoscrypt import __version__
|
||||||
r = self._run(["--version"])
|
r = self._run(["--version"])
|
||||||
assert r.returncode == 0
|
assert r.returncode == 0
|
||||||
assert "2.1.6" in r.stdout
|
assert __version__ in r.stdout
|
||||||
|
|
||||||
def test_help_mentions_scope(self):
|
def test_help_mentions_scope(self):
|
||||||
r = self._run(["--help"])
|
r = self._run(["--help"])
|
||||||
@@ -548,6 +609,49 @@ class TestCLI:
|
|||||||
assert r.returncode == 0, r.stderr
|
assert r.returncode == 0, r.stderr
|
||||||
assert open(dst, encoding="utf-8").read() == "file cli test"
|
assert open(dst, encoding="utf-8").read() == "file cli test"
|
||||||
|
|
||||||
|
def test_json_flag_accepted_before_and_after_subcommand(self, tmp_path):
|
||||||
|
"""--json must work in either position, not only before the subcommand."""
|
||||||
|
kf = str(tmp_path / "pos.key")
|
||||||
|
self._run(["keygen", "-k", kf, "-P", KEY_PWD])
|
||||||
|
|
||||||
|
for args in (
|
||||||
|
["--json", "info", "-k", kf, "-P", KEY_PWD],
|
||||||
|
["info", "-k", kf, "-P", KEY_PWD, "--json"],
|
||||||
|
):
|
||||||
|
r = self._run(args)
|
||||||
|
assert r.returncode == 0, r.stderr
|
||||||
|
assert json.loads(r.stdout)["ok"] is True, args
|
||||||
|
|
||||||
|
def test_quiet_flag_accepted_before_and_after_subcommand(self, tmp_path):
|
||||||
|
kf = str(tmp_path / "q.key")
|
||||||
|
self._run(["keygen", "-k", kf, "-P", KEY_PWD])
|
||||||
|
|
||||||
|
for args in (
|
||||||
|
["--quiet", "encrypt", "x", "-p", USER_PWD, "-k", kf, "-P", KEY_PWD],
|
||||||
|
["encrypt", "x", "-p", USER_PWD, "-k", kf, "-P", KEY_PWD, "--quiet"],
|
||||||
|
):
|
||||||
|
r = self._run(args)
|
||||||
|
assert r.returncode == 0, r.stderr
|
||||||
|
assert r.stdout.strip() == "", args
|
||||||
|
|
||||||
|
def test_plain_output_is_bare_ciphertext(self, tmp_path):
|
||||||
|
"""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
|
||||||
|
assert not out.startswith("{"), "unexpected JSON envelope"
|
||||||
|
assert out.startswith(MAGIC.decode())
|
||||||
|
int(strip_header(out), 16)
|
||||||
|
|
||||||
def test_chpwd(self, tmp_path):
|
def test_chpwd(self, tmp_path):
|
||||||
kf = str(tmp_path / "c.key")
|
kf = str(tmp_path / "c.key")
|
||||||
self._run(["keygen", "-k", kf, "-P", KEY_PWD])
|
self._run(["keygen", "-k", kf, "-P", KEY_PWD])
|
||||||
@@ -564,12 +668,17 @@ class TestCLI:
|
|||||||
# ---------------------------------------------------------------------------
|
# ---------------------------------------------------------------------------
|
||||||
class TestCoreDirect:
|
class TestCoreDirect:
|
||||||
def test_core_generate_and_use(self):
|
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()
|
c = ChaosCryptCore()
|
||||||
data = c.generate_keymaterial()
|
data = c.generate_keymaterial()
|
||||||
ct = c.encrypt_text("core direct", USER_PWD)
|
ct = c.encrypt_text("core direct", USER_PWD)
|
||||||
assert c.decrypt_text(ct, USER_PWD) == "core direct"
|
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 = ChaosCryptCore()
|
||||||
c2.load_keys_from_text(text, KEY_PWD)
|
c2.load_keys_from_text(text, KEY_PWD)
|
||||||
assert c2.decrypt_text(ct, USER_PWD) == "core direct"
|
assert c2.decrypt_text(ct, USER_PWD) == "core direct"
|
||||||
|
|||||||
@@ -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
|
The break is intentional in both directions:
|
||||||
library, and
|
|
||||||
* ciphertext produced by the packaged library decrypts with the original
|
|
||||||
script.
|
|
||||||
|
|
||||||
They are the regression guard for the promise that the algorithm itself was
|
* a key file written by this version cannot be read by the original script;
|
||||||
ported without any behavioural change.
|
* 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
|
import pytest
|
||||||
|
|
||||||
from chaoscrypt import ChaosCrypt
|
|
||||||
|
|
||||||
KEY_PWD = "legacy-key-password"
|
@pytest.mark.skip(reason="interoperability with pre-4.2.6 artefacts was "
|
||||||
USER_PWD = "legacy-user-password"
|
"intentionally dropped when the header was added; "
|
||||||
|
"see the compatibility API instead")
|
||||||
SAMPLES = [
|
def test_legacy_interop_removed():
|
||||||
"legacy compatibility",
|
"""Placeholder so the removal shows up in the test report."""
|
||||||
"兼容性检查",
|
assert True
|
||||||
"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
|
|
||||||
|
|||||||
@@ -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"
|
||||||
@@ -62,7 +62,7 @@ class TestTUI:
|
|||||||
seq = (f"5\nt.key\n{KEY_PWD}\n{KEY_PWD}\n\n"
|
seq = (f"5\nt.key\n{KEY_PWD}\n{KEY_PWD}\n\n"
|
||||||
f"1\nsecret payload\n{USER_PWD}\n\nq\n")
|
f"1\nsecret payload\n{USER_PWD}\n\nq\n")
|
||||||
r1 = _run_tui(seq, str(tmp_path))
|
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
|
assert m, r1.stdout
|
||||||
ct = m.group(1).strip()
|
ct = m.group(1).strip()
|
||||||
|
|
||||||
@@ -73,7 +73,7 @@ class TestTUI:
|
|||||||
def test_load_remembers_key_file(self, tui_dir):
|
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"
|
seq = f"6\nt.key\n{KEY_PWD}\n\n1\nremembers\n{USER_PWD}\n\nq\n"
|
||||||
r = _run_tui(seq, tui_dir)
|
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):
|
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"
|
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"
|
seq = (f"6\nt.key\n{KEY_PWD}\n\n9\n2\n\n"
|
||||||
f"1\n中文内容\n{USER_PWD}\n\nq\n")
|
f"1\n中文内容\n{USER_PWD}\n\nq\n")
|
||||||
r = _run_tui(seq, tui_dir)
|
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):
|
def test_about_page_has_design_notes(self, tmp_path):
|
||||||
r = _run_tui("a\n\nq\n", str(tmp_path))
|
r = _run_tui("a\n\nq\n", str(tmp_path))
|
||||||
|
|||||||
@@ -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
@@ -15,7 +15,8 @@ import os
|
|||||||
import sys
|
import sys
|
||||||
from typing import Optional
|
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 .errors import ChaosCryptError
|
||||||
from .i18n import DEFAULT_LANG, LANG_NAMES, t
|
from .i18n import DEFAULT_LANG, LANG_NAMES, t
|
||||||
|
|
||||||
@@ -135,10 +136,14 @@ class TUI:
|
|||||||
"""Menu-driven bilingual interface over :class:`~chaoscrypt.ChaosCrypt`."""
|
"""Menu-driven bilingual interface over :class:`~chaoscrypt.ChaosCrypt`."""
|
||||||
|
|
||||||
def __init__(self, lang: str = DEFAULT_LANG,
|
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.lang = lang if lang in LANG_NAMES else DEFAULT_LANG
|
||||||
self.key_file = key_file
|
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
|
self.key_password: Optional[str] = None
|
||||||
|
|
||||||
# ------------------------------------------------------------------ view
|
# ------------------------------------------------------------------ view
|
||||||
@@ -162,7 +167,7 @@ class TUI:
|
|||||||
if self.cc.loaded
|
if self.cc.loaded
|
||||||
else c("[ ] " + self._tr("no_key_loaded"), "red")
|
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:
|
def _print_error(self, exc: Exception) -> None:
|
||||||
"""Render a unified error, with a hint where one applies."""
|
"""Render a unified error, with a hint where one applies."""
|
||||||
@@ -190,6 +195,8 @@ class TUI:
|
|||||||
("7", "menu_keyinfo"),
|
("7", "menu_keyinfo"),
|
||||||
("8", "menu_chpwd"),
|
("8", "menu_chpwd"),
|
||||||
("9", "menu_lang"),
|
("9", "menu_lang"),
|
||||||
|
("m", "menu_mode"),
|
||||||
|
("e", "menu_encoding"),
|
||||||
("a", "menu_about"),
|
("a", "menu_about"),
|
||||||
("q", "menu_quit"),
|
("q", "menu_quit"),
|
||||||
]
|
]
|
||||||
@@ -361,6 +368,8 @@ class TUI:
|
|||||||
("info_short_key",
|
("info_short_key",
|
||||||
f"{info['short_key_length']} {self._tr('characters')}"),
|
f"{info['short_key_length']} {self._tr('characters')}"),
|
||||||
("info_loaded", self._tr("yes")),
|
("info_loaded", self._tr("yes")),
|
||||||
|
("info_mode", self.mode),
|
||||||
|
("info_encoding", self.encoding),
|
||||||
]
|
]
|
||||||
print()
|
print()
|
||||||
print(c(_rule(), "dim"))
|
print(c(_rule(), "dim"))
|
||||||
@@ -405,6 +414,69 @@ class TUI:
|
|||||||
self.lang = choice
|
self.lang = choice
|
||||||
print(c(f" -> {LANG_NAMES[self.lang]}", "green"))
|
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:
|
def action_about(self) -> None:
|
||||||
print()
|
print()
|
||||||
print(c(self._tr("about_body"), "cyan"))
|
print(c(self._tr("about_body"), "cyan"))
|
||||||
@@ -439,6 +511,10 @@ class TUI:
|
|||||||
self.action_chpwd()
|
self.action_chpwd()
|
||||||
elif choice == "9":
|
elif choice == "9":
|
||||||
self.action_lang()
|
self.action_lang()
|
||||||
|
elif choice in ("m", "mode"):
|
||||||
|
self.action_mode()
|
||||||
|
elif choice in ("e", "encoding"):
|
||||||
|
self.action_encoding()
|
||||||
elif choice in ("a", "about"):
|
elif choice in ("a", "about"):
|
||||||
self.action_about()
|
self.action_about()
|
||||||
elif choice in ("q", "quit", "exit"):
|
elif choice in ("q", "quit", "exit"):
|
||||||
|
|||||||
+122
@@ -21,6 +21,12 @@ from chaoscrypt import ChaosCryptError # base error class
|
|||||||
| `decrypt` | function | One-shot decrypt using a key file |
|
| `decrypt` | function | One-shot decrypt using a key file |
|
||||||
| `create_key` | function | One-shot key file generation |
|
| `create_key` | function | One-shot key file generation |
|
||||||
| `DEFAULT_KEY_FILE` | constant | `"encryption.key"` |
|
| `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`) |
|
| `KEYFILE_VERSION` | constant | On-disk key file format version (`1`) |
|
||||||
| `__version__` | constant | Library version string |
|
| `__version__` | constant | Library version string |
|
||||||
| `__license__` | constant | `"MIT"` |
|
| `__license__` | constant | `"MIT"` |
|
||||||
@@ -50,6 +56,9 @@ ChaosCrypt(
|
|||||||
| `key_password` | `str \| None` | `None` | Password protecting that key file |
|
| `key_password` | `str \| None` | `None` | Password protecting that key file |
|
||||||
| `auto_load` | `bool` | `False` | Load the key file during construction |
|
| `auto_load` | `bool` | `False` | Load the key file during construction |
|
||||||
| `default_key_file` | `str` | `"encryption.key"` | File name used when `key_file` is omitted |
|
| `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
|
When `auto_load=True` and the file cannot be loaded, the corresponding
|
||||||
exception is raised from the constructor.
|
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
|
## Error hierarchy
|
||||||
|
|
||||||
Every error is a subclass of `ChaosCryptError`, so a single `except` clause
|
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 |
|
| `E014` | `ChaosCrypt_ERR_FileReadFailed_E014` | Reading a file failed |
|
||||||
| `E015` | `ChaosCrypt_ERR_FileWriteFailed_E015` | Writing a file failed |
|
| `E015` | `ChaosCrypt_ERR_FileWriteFailed_E015` | Writing a file failed |
|
||||||
| `E016` | `ChaosCrypt_ERR_UnsupportedKeyVersion_E016` | Key file version not supported |
|
| `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
|
Codes are stable and safe to branch on. The human-readable portion of the
|
||||||
message may be reworded between minor releases.
|
message may be reworded between minor releases.
|
||||||
|
|||||||
+618
@@ -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.
|
||||||
@@ -7,6 +7,7 @@ Reference material for ChaosCrypt.
|
|||||||
| [API.md](API.md) | Complete Python API reference |
|
| [API.md](API.md) | Complete Python API reference |
|
||||||
| [CLI.md](CLI.md) | Command line reference, pipelines, troubleshooting |
|
| [CLI.md](CLI.md) | Command line reference, pipelines, troubleshooting |
|
||||||
| [ARCHITECTURE.md](ARCHITECTURE.md) | Module map, data flow, design decisions |
|
| [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 |
|
| [BUILDING.md](BUILDING.md) | Building, testing and releasing |
|
||||||
| [../SECURITY.md](../SECURITY.md) | Design, key space, threat model, attack analysis |
|
| [../SECURITY.md](../SECURITY.md) | Design, key space, threat model, attack analysis |
|
||||||
| [../README.md](../README.md) | Project overview and quick start |
|
| [../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**
|
**Using the command line**
|
||||||
[CLI.md](CLI.md) — covers every subcommand, plus pipelines and shell aliases.
|
[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**
|
**Understanding how it works**
|
||||||
[ARCHITECTURE.md](ARCHITECTURE.md) for the code structure, and
|
[ARCHITECTURE.md](ARCHITECTURE.md) for the code structure, and
|
||||||
[SECURITY.md §3](../SECURITY.md) for the algorithm itself.
|
[SECURITY.md §3](../SECURITY.md) for the algorithm itself.
|
||||||
|
|||||||
@@ -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
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
|
|||||||
|
|
||||||
[project]
|
[project]
|
||||||
name = "chaoscrypt"
|
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."
|
description = "A chaos-based obfuscation cipher with a bilingual TUI, a full CLI and a clean Python API."
|
||||||
readme = "README.md"
|
readme = "README.md"
|
||||||
requires-python = ">=3.8"
|
requires-python = ">=3.8"
|
||||||
@@ -93,8 +93,19 @@ chaoscrypt = "chaoscrypt.cli:cli_main"
|
|||||||
# ---------------------------------------------------------------------------
|
# ---------------------------------------------------------------------------
|
||||||
[tool.setuptools]
|
[tool.setuptools]
|
||||||
py-modules = []
|
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"]
|
packages = ["chaoscrypt"]
|
||||||
|
|
||||||
|
[tool.setuptools.exclude-package-data]
|
||||||
|
chaoscrypt = [
|
||||||
|
"tests/*",
|
||||||
|
"examples/*",
|
||||||
|
"legacy/*",
|
||||||
|
]
|
||||||
|
|
||||||
[tool.setuptools.package-data]
|
[tool.setuptools.package-data]
|
||||||
chaoscrypt = ["py.typed"]
|
chaoscrypt = ["py.typed"]
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user