KRANSX
Authenticated encryption with adaptive compression for Python.
KRANSX seals arbitrary bytes into a compact, authenticated envelope. It tries Zstandard (at your level and 19) and LZMA-6, keeps the strictly smallest result or stores the payload as-is, and protects the winner with AES-256-GCM-SIV. The result is a single self-contained binary with 29 bytes of overhead.
Features
- Adaptive compression — codec tournament (Zstandard at level and 19, LZMA-6) when beneficial, raw otherwise
- Authenticated encryption — AES-256-GCM-SIV (nonce-misuse resistant)
- Small fixed overhead — 29 bytes (
suite+nonce+tag) - Simple API —
seal/open_data, fully typed - Dictionary support — optional Zstandard dictionaries for structured data
- CLI —
keygen,seal,open,train,bench - No background services or async dependencies
Installation
pip install kransx
For development:
uv sync --locked --extra dev
Requires Python 3.10+, cryptography >= 42, zstandard >= 0.22.
Usage
Python API
import secrets
from kransx import open_data, seal
key = secrets.token_bytes(32) # 32 uniformly random bytes
aad = b"record-42" # associated data, authenticated but not encrypted
sealed = seal(b"hello world", key, aad=aad)
assert open_data(sealed, key, aad=aad) == b"hello world"
Authentication failures raise cryptography.exceptions.InvalidTag (wrong key, AAD, dictionary, or modified bytes). Structural errors raise ValueError.
With a shared dictionary (non-secret, improves compression on similar payloads):
from kransx import train_dict
dictionary = train_dict([b'{"user":1,"action":"login"}'] * 300)
sealed = seal(b'{"user":1,"action":"login"}', key, dict_obj=dictionary)
assert open_data(sealed, key, dict_obj=dictionary) == b'{"user":1,"action":"login"}'
API reference:
seal(data: bytes, key: bytes, *, dict_obj=None, aad=b"", compress=True, level=3) -> bytes
open_data(blob: bytes, key: bytes, *, dict_obj=None, aad=b"", max_output_size=64*1024*1024) -> bytes
train_dict(samples: Iterable[bytes], dict_size=16384) -> ZstdCompressionDict
save_dict(dictionary, path) / load_dict(path)
compress=True runs the codec tournament and keeps the strictly smallest payload; raw wins all ties. max_output_size limits the decompressed output size.
CLI
kransx keygen key.bin
kransx seal plain.bin sealed.bin --key-file key.bin --aad 7265636f72642d3432
kransx open sealed.bin restored.bin --key-file key.bin --aad 7265636f72642d3432
kransx train 'samples/*.json' --output model.dict
kransx seal plain.bin out.bin --key-file key.bin --dict model.dict
kransx open out.bin restored.bin --key-file key.bin --dict model.dict --max-output-size 1048576
kransx bench
benchruns the A+B claim gates (tournament bound, overhead floor); exit non-zero on failure--aadaccepts hex-encoded bytes--max-output-sizecaps plaintext size on open- Output files are created exclusively and never overwritten
Design
Envelope layout: suite (1) | nonce (12) | ciphertext | tag (16)
| Suite | Payload | Authenticated associated data |
|---|---|---|
0x21 |
Zstandard frame | suite + dictionary binding + aad |
0x22 |
raw bytes | suite + aad |
0x23 |
LZMA bytes (preset 6) | suite + no-dictionary binding + aad |
- The dictionary binding is
SHA-256over the dictionary bytes (or a constant for no dictionary), ensuring a mismatched dictionary fails authentication before decompression. - Keys are 32 random bytes expanded via HKDF-SHA256 to the AEAD key. A fresh 12-byte nonce is generated per seal.
- Opening validates the envelope before decryption: size and suite checks, then AEAD authentication, then — for compressed payloads — single-frame Zstandard validation and bounded decompression.
Security considerations
This library implements the envelope only. Key generation, distribution, storage, rotation, and encrypted-input size bounding are the caller's responsibility.
- Keys must be 32 uniformly random bytes. Passwords are not valid keys.
- Nonces are generated with
os.urandom(12)per seal. AES-GCM-SIV is nonce-misuse resistant, but reuse should still be avoided. - Compression oracles — the sealed size reveals whether compression was used. Do not compress data that mixes secrets with attacker-controlled input without application-level separation. Use
compress=Falsewhen this is a concern. - Resource limits —
max_output_sizebounds decompressed output. For untrusted inputs, also bound the encrypted input size before callingopen_data.
Development
uv sync --locked --extra dev
uv run ruff check .
uv run mypy kransx
uv run pytest -q
Pre-commit hooks are configured for ruff and mypy (see .pre-commit-config.yaml).
kransx/ seal, open_data, dicts, cli
tests/ conformance vectors, tamper checks, resource limits
License
MIT — see LICENSE.
Metadata
Release files for kransx 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| kransx-0.2.0.tar.gz | 14.9 kB | Without provenance | Details for kransx-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| kransx-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for kransx-0.2.0-py3-none-any.whl |
Total release size: 24.7 kB
Release files / kransx-0.2.0.tar.gz
| Download URL | kransx-0.2.0.tar.gz |
|---|---|
| Size | 14.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a113fa9a448d5602c296104231130bffd4ef2f070f3dc35bfcd0c92e603f3b75
|
|
BLAKE2b-256 checksum How to use checksums |
0114ec4197ad86853c4a3ffa019755649262e325dbce3338feeec6c98ac192f9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.9 {"installer":{"name":"uv","version":"0.12.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / kransx-0.2.0-py3-none-any.whl
| Download URL | kransx-0.2.0-py3-none-any.whl |
|---|---|
| Size | 9.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
434cf189b68c08fbb98396b33713264ba27bca69a7b75af9e549b81ca79882c8
|
|
BLAKE2b-256 checksum How to use checksums |
f42256f82472823a562c245481942642b96e9a235db7173180c8dd9bea9542d2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.9 {"installer":{"name":"uv","version":"0.12.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for kransx 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.