# 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).