Skip to main content

KRANSX

PyPI Python 3.10+ License: MIT

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
  • bench runs the A+B claim gates (tournament bound, overhead floor); exit non-zero on failure
  • --aad accepts hex-encoded bytes
  • --max-output-size caps 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-256 over 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=False when this is a concern.
  • Resource limits — max_output_size bounds decompressed output. For untrusted inputs, also bound the encrypted input size before calling open_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)

Source distribution for kransx 0.2.0
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)

Table of built distributions (wheels) for kransx 0.2.0
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page