kransx 0.2.0__tar.gz → 0.2.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
kransx-0.2.1/PKG-INFO ADDED
@@ -0,0 +1,155 @@
1
+ Metadata-Version: 2.4
2
+ Name: kransx
3
+ Version: 0.2.1
4
+ Summary: KRANSX authenticated encryption-envelope reference implementation
5
+ Author: KRANSX contributors
6
+ License-Expression: MIT
7
+ Keywords: aead,compression,encryption,zstandard
8
+ Classifier: Development Status :: 3 - Alpha
9
+ Classifier: Intended Audience :: Developers
10
+ Classifier: Topic :: Security :: Cryptography
11
+ Classifier: Topic :: System :: Archiving :: Compression
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Programming Language :: Python :: 3.10
14
+ Classifier: Programming Language :: Python :: 3.11
15
+ Classifier: Programming Language :: Python :: 3.12
16
+ Classifier: Programming Language :: Python :: 3.13
17
+ Classifier: Programming Language :: Python :: 3.14
18
+ Classifier: Operating System :: OS Independent
19
+ Classifier: Typing :: Typed
20
+ Requires-Python: >=3.10
21
+ Description-Content-Type: text/markdown
22
+ License-File: LICENSE
23
+ Requires-Dist: cryptography>=42
24
+ Requires-Dist: zstandard>=0.22
25
+ Provides-Extra: dev
26
+ Requires-Dist: mypy>=1.10; extra == "dev"
27
+ Requires-Dist: pre-commit>=4; extra == "dev"
28
+ Requires-Dist: pytest>=7; extra == "dev"
29
+ Requires-Dist: ruff>=0.4; extra == "dev"
30
+ Dynamic: license-file
31
+
32
+ # KRANSX
33
+
34
+ [![PyPI](https://img.shields.io/pypi/v/kransx.svg)](https://pypi.org/project/kransx/)
35
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org)
36
+ [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
37
+
38
+ ```python
39
+ import secrets
40
+ from kransx import open_data, seal
41
+
42
+ key = secrets.token_bytes(32)
43
+ sealed = seal(b"hello world", key, aad=b"record-42")
44
+ assert open_data(sealed, key, aad=b"record-42") == b"hello world"
45
+ ```
46
+
47
+ KRANSX picks the smallest of Zstandard, LZMA-6, and raw for every payload, then encrypts the winner with AES-256-GCM-SIV. Fixed cost: 29 bytes per envelope (1 suite + 12 nonce + 16 tag). Wrong key, wrong associated data, wrong dictionary, or modified bytes fail with `cryptography.exceptions.InvalidTag`. Malformed envelopes fail with `ValueError` before anything decrypts.
48
+
49
+ ## Installation
50
+
51
+ ```bash
52
+ pip install kransx
53
+ ```
54
+
55
+ Development setup:
56
+
57
+ ```bash
58
+ uv sync --locked --extra dev
59
+ ```
60
+
61
+ Requires Python 3.10+, `cryptography >= 42`, `zstandard >= 0.22`.
62
+
63
+ ## Measured behavior
64
+
65
+ Each line below is decided by a checked-in command that exits non-zero when broken.
66
+
67
+ | Behavior | Evidence | Command |
68
+ |---|---|---|
69
+ | Sealed output never exceeds the best single codec plus 29 bytes | 8 corpora, worst margin 0 | `kransx bench` |
70
+ | Overhead is exactly 29 bytes, empty to 1 MB | 8 sizes, all raw suite | `kransx bench` |
71
+ | Small JSON records seal 45% smaller with a trained dictionary | ratio 0.552 vs 0.85 gate, 5,000 records | `uv run python bench/bench_claim_c1_dict.py` |
72
+ | Tamper at any envelope offset is rejected | tamper and failure matrix, exact exceptions | `uv run pytest -q` (71 tests) |
73
+
74
+ ## Python API
75
+
76
+ | Method | Functionality |
77
+ |---|---|
78
+ | `seal` | Compresses the payload with the codec tournament, then encrypts the winner into a 29-byte-overhead envelope. |
79
+ | `open_data` | Authenticates the envelope, decrypts it, and decompresses the payload without exceeding `max_output_size`. |
80
+ | `train_dict` | Learns a Zstandard dictionary from sample payloads so small, similar messages compress smaller. |
81
+ | `save_dict` / `load_dict` | Writes a trained dictionary to disk and reads it back for reuse across runs. |
82
+
83
+ `compress=True` runs the tournament and keeps the strictly smallest payload. Raw wins every tie, so incompressible input grows by exactly the 29-byte floor and nothing more. `max_output_size` caps decompressed output. Structural problems raise `ValueError`. Authentication problems raise `InvalidTag` and release no plaintext.
84
+
85
+ Shared dictionaries are non-secret compression aids for similar payloads:
86
+
87
+ ```python
88
+ from kransx import train_dict
89
+
90
+ dictionary = train_dict([b'{"user":1,"action":"login"}'] * 300)
91
+ sealed = seal(b'{"user":1,"action":"login"}', key, dict_obj=dictionary)
92
+ assert open_data(sealed, key, dict_obj=dictionary) == b'{"user":1,"action":"login"}'
93
+ ```
94
+
95
+ A mismatched dictionary fails authentication before decompression starts.
96
+
97
+ ## CLI
98
+
99
+ ```bash
100
+ kransx keygen key.bin
101
+ kransx seal plain.bin sealed.bin --key-file key.bin --aad 7265636f72642d3432
102
+ kransx open sealed.bin restored.bin --key-file key.bin --aad 7265636f72642d3432
103
+
104
+ kransx train 'samples/*.json' --output model.dict
105
+ kransx seal plain.bin out.bin --key-file key.bin --dict model.dict
106
+ kransx open out.bin restored.bin --key-file key.bin --dict model.dict --max-output-size 1048576
107
+ kransx bench
108
+ ```
109
+
110
+ - `--aad` takes hex-encoded bytes.
111
+ - `--max-output-size` caps plaintext size on open.
112
+ - Output files are created exclusively and never overwritten.
113
+ - `bench` reruns the A+B claim gates and fails non-zero on any regression.
114
+
115
+ ## Design
116
+
117
+ Envelope layout: `suite (1) | nonce (12) | ciphertext | tag (16)`.
118
+
119
+ | Suite | Payload | Authenticated associated data |
120
+ |-------|---------|-------------------------------|
121
+ | `0x21` | Zstandard frame | `suite` + dictionary binding + `aad` |
122
+ | `0x22` | raw bytes | `suite` + `aad` |
123
+ | `0x23` | LZMA bytes (preset 6) | `suite` + no-dictionary binding + `aad` |
124
+
125
+ The dictionary binding is `SHA-256` over the dictionary bytes, or over a fixed constant when no dictionary is used. Keys are 32 random bytes expanded through HKDF-SHA-256 to the AEAD key. Every seal generates a fresh 12-byte nonce. Opening checks size and suite first, authenticates second, and only then decompresses under the output cap: single Zstandard frame or a bounded LZMA stream, trailing bytes rejected either way.
126
+
127
+ ## Security
128
+
129
+ This library is the envelope only. Key generation, distribution, storage, rotation, and bounding encrypted-input size stay with the caller.
130
+
131
+ - **Keys** must be 32 uniformly random bytes. Passwords are not valid keys.
132
+ - **Nonces** come from `os.urandom(12)` per seal. AES-GCM-SIV tolerates reuse better than most modes, but do not reuse them.
133
+ - **Compression oracles.** Sealed size reveals which suite won. Never compress secrets mixed with attacker-controlled input without application-level separation. Pass `compress=False` when in doubt.
134
+ - **Resource limits.** `max_output_size` bounds decompressed output. For untrusted input, also cap the encrypted bytes before calling `open_data`.
135
+
136
+ This is an implementation with conformance vectors and tamper coverage, not an external audit.
137
+
138
+ ## Development
139
+
140
+ ```bash
141
+ uv sync --locked --extra dev
142
+ uv run ruff check .
143
+ uv run mypy kransx
144
+ uv run pytest -q
145
+ ```
146
+
147
+ Layout: `kransx/` holds seal, open, dicts, cli. `tests/` holds conformance vectors, tamper checks, resource limits. `bench/` holds the claim gates and their result snapshots.
148
+
149
+ ## License
150
+
151
+ MIT — see [LICENSE](LICENSE).
152
+
153
+ ## Changelog
154
+
155
+ See [CHANGELOG.md](CHANGELOG.md).
kransx-0.2.1/README.md ADDED
@@ -0,0 +1,124 @@
1
+ # KRANSX
2
+
3
+ [![PyPI](https://img.shields.io/pypi/v/kransx.svg)](https://pypi.org/project/kransx/)
4
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org)
5
+ [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
6
+
7
+ ```python
8
+ import secrets
9
+ from kransx import open_data, seal
10
+
11
+ key = secrets.token_bytes(32)
12
+ sealed = seal(b"hello world", key, aad=b"record-42")
13
+ assert open_data(sealed, key, aad=b"record-42") == b"hello world"
14
+ ```
15
+
16
+ KRANSX picks the smallest of Zstandard, LZMA-6, and raw for every payload, then encrypts the winner with AES-256-GCM-SIV. Fixed cost: 29 bytes per envelope (1 suite + 12 nonce + 16 tag). Wrong key, wrong associated data, wrong dictionary, or modified bytes fail with `cryptography.exceptions.InvalidTag`. Malformed envelopes fail with `ValueError` before anything decrypts.
17
+
18
+ ## Installation
19
+
20
+ ```bash
21
+ pip install kransx
22
+ ```
23
+
24
+ Development setup:
25
+
26
+ ```bash
27
+ uv sync --locked --extra dev
28
+ ```
29
+
30
+ Requires Python 3.10+, `cryptography >= 42`, `zstandard >= 0.22`.
31
+
32
+ ## Measured behavior
33
+
34
+ Each line below is decided by a checked-in command that exits non-zero when broken.
35
+
36
+ | Behavior | Evidence | Command |
37
+ |---|---|---|
38
+ | Sealed output never exceeds the best single codec plus 29 bytes | 8 corpora, worst margin 0 | `kransx bench` |
39
+ | Overhead is exactly 29 bytes, empty to 1 MB | 8 sizes, all raw suite | `kransx bench` |
40
+ | Small JSON records seal 45% smaller with a trained dictionary | ratio 0.552 vs 0.85 gate, 5,000 records | `uv run python bench/bench_claim_c1_dict.py` |
41
+ | Tamper at any envelope offset is rejected | tamper and failure matrix, exact exceptions | `uv run pytest -q` (71 tests) |
42
+
43
+ ## Python API
44
+
45
+ | Method | Functionality |
46
+ |---|---|
47
+ | `seal` | Compresses the payload with the codec tournament, then encrypts the winner into a 29-byte-overhead envelope. |
48
+ | `open_data` | Authenticates the envelope, decrypts it, and decompresses the payload without exceeding `max_output_size`. |
49
+ | `train_dict` | Learns a Zstandard dictionary from sample payloads so small, similar messages compress smaller. |
50
+ | `save_dict` / `load_dict` | Writes a trained dictionary to disk and reads it back for reuse across runs. |
51
+
52
+ `compress=True` runs the tournament and keeps the strictly smallest payload. Raw wins every tie, so incompressible input grows by exactly the 29-byte floor and nothing more. `max_output_size` caps decompressed output. Structural problems raise `ValueError`. Authentication problems raise `InvalidTag` and release no plaintext.
53
+
54
+ Shared dictionaries are non-secret compression aids for similar payloads:
55
+
56
+ ```python
57
+ from kransx import train_dict
58
+
59
+ dictionary = train_dict([b'{"user":1,"action":"login"}'] * 300)
60
+ sealed = seal(b'{"user":1,"action":"login"}', key, dict_obj=dictionary)
61
+ assert open_data(sealed, key, dict_obj=dictionary) == b'{"user":1,"action":"login"}'
62
+ ```
63
+
64
+ A mismatched dictionary fails authentication before decompression starts.
65
+
66
+ ## CLI
67
+
68
+ ```bash
69
+ kransx keygen key.bin
70
+ kransx seal plain.bin sealed.bin --key-file key.bin --aad 7265636f72642d3432
71
+ kransx open sealed.bin restored.bin --key-file key.bin --aad 7265636f72642d3432
72
+
73
+ kransx train 'samples/*.json' --output model.dict
74
+ kransx seal plain.bin out.bin --key-file key.bin --dict model.dict
75
+ kransx open out.bin restored.bin --key-file key.bin --dict model.dict --max-output-size 1048576
76
+ kransx bench
77
+ ```
78
+
79
+ - `--aad` takes hex-encoded bytes.
80
+ - `--max-output-size` caps plaintext size on open.
81
+ - Output files are created exclusively and never overwritten.
82
+ - `bench` reruns the A+B claim gates and fails non-zero on any regression.
83
+
84
+ ## Design
85
+
86
+ Envelope layout: `suite (1) | nonce (12) | ciphertext | tag (16)`.
87
+
88
+ | Suite | Payload | Authenticated associated data |
89
+ |-------|---------|-------------------------------|
90
+ | `0x21` | Zstandard frame | `suite` + dictionary binding + `aad` |
91
+ | `0x22` | raw bytes | `suite` + `aad` |
92
+ | `0x23` | LZMA bytes (preset 6) | `suite` + no-dictionary binding + `aad` |
93
+
94
+ The dictionary binding is `SHA-256` over the dictionary bytes, or over a fixed constant when no dictionary is used. Keys are 32 random bytes expanded through HKDF-SHA-256 to the AEAD key. Every seal generates a fresh 12-byte nonce. Opening checks size and suite first, authenticates second, and only then decompresses under the output cap: single Zstandard frame or a bounded LZMA stream, trailing bytes rejected either way.
95
+
96
+ ## Security
97
+
98
+ This library is the envelope only. Key generation, distribution, storage, rotation, and bounding encrypted-input size stay with the caller.
99
+
100
+ - **Keys** must be 32 uniformly random bytes. Passwords are not valid keys.
101
+ - **Nonces** come from `os.urandom(12)` per seal. AES-GCM-SIV tolerates reuse better than most modes, but do not reuse them.
102
+ - **Compression oracles.** Sealed size reveals which suite won. Never compress secrets mixed with attacker-controlled input without application-level separation. Pass `compress=False` when in doubt.
103
+ - **Resource limits.** `max_output_size` bounds decompressed output. For untrusted input, also cap the encrypted bytes before calling `open_data`.
104
+
105
+ This is an implementation with conformance vectors and tamper coverage, not an external audit.
106
+
107
+ ## Development
108
+
109
+ ```bash
110
+ uv sync --locked --extra dev
111
+ uv run ruff check .
112
+ uv run mypy kransx
113
+ uv run pytest -q
114
+ ```
115
+
116
+ Layout: `kransx/` holds seal, open, dicts, cli. `tests/` holds conformance vectors, tamper checks, resource limits. `bench/` holds the claim gates and their result snapshots.
117
+
118
+ ## License
119
+
120
+ MIT — see [LICENSE](LICENSE).
121
+
122
+ ## Changelog
123
+
124
+ See [CHANGELOG.md](CHANGELOG.md).
@@ -3,6 +3,6 @@
3
3
  from .core import open_data, seal
4
4
  from .dicts import load_dict, save_dict, train_dict
5
5
 
6
- __version__ = "0.2.0"
6
+ __version__ = "0.2.1"
7
7
 
8
8
  __all__ = ["seal", "open_data", "train_dict", "save_dict", "load_dict", "__version__"]
@@ -56,9 +56,9 @@ def _decompress(payload: bytes, dict_obj: zstd.ZstdCompressionDict | None, limit
56
56
  raise ValueError("invalid Zstandard frame")
57
57
  if advertised_size != zstd.CONTENTSIZE_UNKNOWN and advertised_size > limit:
58
58
  raise ValueError("decompressed data exceeds max_output_size")
59
- return zstd.ZstdDecompressor(
60
- dict_data=dict_obj, max_window_size=max(1, (limit + 1023) // 1024)
61
- ).decompress(payload, max_output_size=limit, allow_extra_data=False)
59
+ return zstd.ZstdDecompressor(dict_data=dict_obj).decompress(
60
+ payload, max_output_size=limit, allow_extra_data=False
61
+ )
62
62
  except zstd.ZstdError as error:
63
63
  raise ValueError("invalid or oversized Zstandard payload") from error
64
64
 
@@ -108,11 +108,12 @@ def seal(
108
108
  suite = 0x22
109
109
  used_dict: zstd.ZstdCompressionDict | None = None
110
110
  if compress:
111
+ zstd_levels = (level,) if level == 19 else (level, 19)
111
112
  contenders: list[tuple[bytes, int, zstd.ZstdCompressionDict | None]] = [
112
- (zstd.ZstdCompressor(level=level, dict_data=dict_obj).compress(data), 0x21, dict_obj),
113
- (zstd.ZstdCompressor(level=19, dict_data=dict_obj).compress(data), 0x21, dict_obj),
114
- (lzma.compress(data, preset=6), 0x23, None),
113
+ (zstd.ZstdCompressor(level=lvl, dict_data=dict_obj).compress(data), 0x21, dict_obj)
114
+ for lvl in zstd_levels
115
115
  ]
116
+ contenders.append((lzma.compress(data, preset=6), 0x23, None))
116
117
  for blob_candidate, suite_candidate, dict_candidate in contenders:
117
118
  if len(blob_candidate) < len(payload):
118
119
  payload, suite, used_dict = blob_candidate, suite_candidate, dict_candidate
@@ -0,0 +1,155 @@
1
+ Metadata-Version: 2.4
2
+ Name: kransx
3
+ Version: 0.2.1
4
+ Summary: KRANSX authenticated encryption-envelope reference implementation
5
+ Author: KRANSX contributors
6
+ License-Expression: MIT
7
+ Keywords: aead,compression,encryption,zstandard
8
+ Classifier: Development Status :: 3 - Alpha
9
+ Classifier: Intended Audience :: Developers
10
+ Classifier: Topic :: Security :: Cryptography
11
+ Classifier: Topic :: System :: Archiving :: Compression
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Programming Language :: Python :: 3.10
14
+ Classifier: Programming Language :: Python :: 3.11
15
+ Classifier: Programming Language :: Python :: 3.12
16
+ Classifier: Programming Language :: Python :: 3.13
17
+ Classifier: Programming Language :: Python :: 3.14
18
+ Classifier: Operating System :: OS Independent
19
+ Classifier: Typing :: Typed
20
+ Requires-Python: >=3.10
21
+ Description-Content-Type: text/markdown
22
+ License-File: LICENSE
23
+ Requires-Dist: cryptography>=42
24
+ Requires-Dist: zstandard>=0.22
25
+ Provides-Extra: dev
26
+ Requires-Dist: mypy>=1.10; extra == "dev"
27
+ Requires-Dist: pre-commit>=4; extra == "dev"
28
+ Requires-Dist: pytest>=7; extra == "dev"
29
+ Requires-Dist: ruff>=0.4; extra == "dev"
30
+ Dynamic: license-file
31
+
32
+ # KRANSX
33
+
34
+ [![PyPI](https://img.shields.io/pypi/v/kransx.svg)](https://pypi.org/project/kransx/)
35
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org)
36
+ [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
37
+
38
+ ```python
39
+ import secrets
40
+ from kransx import open_data, seal
41
+
42
+ key = secrets.token_bytes(32)
43
+ sealed = seal(b"hello world", key, aad=b"record-42")
44
+ assert open_data(sealed, key, aad=b"record-42") == b"hello world"
45
+ ```
46
+
47
+ KRANSX picks the smallest of Zstandard, LZMA-6, and raw for every payload, then encrypts the winner with AES-256-GCM-SIV. Fixed cost: 29 bytes per envelope (1 suite + 12 nonce + 16 tag). Wrong key, wrong associated data, wrong dictionary, or modified bytes fail with `cryptography.exceptions.InvalidTag`. Malformed envelopes fail with `ValueError` before anything decrypts.
48
+
49
+ ## Installation
50
+
51
+ ```bash
52
+ pip install kransx
53
+ ```
54
+
55
+ Development setup:
56
+
57
+ ```bash
58
+ uv sync --locked --extra dev
59
+ ```
60
+
61
+ Requires Python 3.10+, `cryptography >= 42`, `zstandard >= 0.22`.
62
+
63
+ ## Measured behavior
64
+
65
+ Each line below is decided by a checked-in command that exits non-zero when broken.
66
+
67
+ | Behavior | Evidence | Command |
68
+ |---|---|---|
69
+ | Sealed output never exceeds the best single codec plus 29 bytes | 8 corpora, worst margin 0 | `kransx bench` |
70
+ | Overhead is exactly 29 bytes, empty to 1 MB | 8 sizes, all raw suite | `kransx bench` |
71
+ | Small JSON records seal 45% smaller with a trained dictionary | ratio 0.552 vs 0.85 gate, 5,000 records | `uv run python bench/bench_claim_c1_dict.py` |
72
+ | Tamper at any envelope offset is rejected | tamper and failure matrix, exact exceptions | `uv run pytest -q` (71 tests) |
73
+
74
+ ## Python API
75
+
76
+ | Method | Functionality |
77
+ |---|---|
78
+ | `seal` | Compresses the payload with the codec tournament, then encrypts the winner into a 29-byte-overhead envelope. |
79
+ | `open_data` | Authenticates the envelope, decrypts it, and decompresses the payload without exceeding `max_output_size`. |
80
+ | `train_dict` | Learns a Zstandard dictionary from sample payloads so small, similar messages compress smaller. |
81
+ | `save_dict` / `load_dict` | Writes a trained dictionary to disk and reads it back for reuse across runs. |
82
+
83
+ `compress=True` runs the tournament and keeps the strictly smallest payload. Raw wins every tie, so incompressible input grows by exactly the 29-byte floor and nothing more. `max_output_size` caps decompressed output. Structural problems raise `ValueError`. Authentication problems raise `InvalidTag` and release no plaintext.
84
+
85
+ Shared dictionaries are non-secret compression aids for similar payloads:
86
+
87
+ ```python
88
+ from kransx import train_dict
89
+
90
+ dictionary = train_dict([b'{"user":1,"action":"login"}'] * 300)
91
+ sealed = seal(b'{"user":1,"action":"login"}', key, dict_obj=dictionary)
92
+ assert open_data(sealed, key, dict_obj=dictionary) == b'{"user":1,"action":"login"}'
93
+ ```
94
+
95
+ A mismatched dictionary fails authentication before decompression starts.
96
+
97
+ ## CLI
98
+
99
+ ```bash
100
+ kransx keygen key.bin
101
+ kransx seal plain.bin sealed.bin --key-file key.bin --aad 7265636f72642d3432
102
+ kransx open sealed.bin restored.bin --key-file key.bin --aad 7265636f72642d3432
103
+
104
+ kransx train 'samples/*.json' --output model.dict
105
+ kransx seal plain.bin out.bin --key-file key.bin --dict model.dict
106
+ kransx open out.bin restored.bin --key-file key.bin --dict model.dict --max-output-size 1048576
107
+ kransx bench
108
+ ```
109
+
110
+ - `--aad` takes hex-encoded bytes.
111
+ - `--max-output-size` caps plaintext size on open.
112
+ - Output files are created exclusively and never overwritten.
113
+ - `bench` reruns the A+B claim gates and fails non-zero on any regression.
114
+
115
+ ## Design
116
+
117
+ Envelope layout: `suite (1) | nonce (12) | ciphertext | tag (16)`.
118
+
119
+ | Suite | Payload | Authenticated associated data |
120
+ |-------|---------|-------------------------------|
121
+ | `0x21` | Zstandard frame | `suite` + dictionary binding + `aad` |
122
+ | `0x22` | raw bytes | `suite` + `aad` |
123
+ | `0x23` | LZMA bytes (preset 6) | `suite` + no-dictionary binding + `aad` |
124
+
125
+ The dictionary binding is `SHA-256` over the dictionary bytes, or over a fixed constant when no dictionary is used. Keys are 32 random bytes expanded through HKDF-SHA-256 to the AEAD key. Every seal generates a fresh 12-byte nonce. Opening checks size and suite first, authenticates second, and only then decompresses under the output cap: single Zstandard frame or a bounded LZMA stream, trailing bytes rejected either way.
126
+
127
+ ## Security
128
+
129
+ This library is the envelope only. Key generation, distribution, storage, rotation, and bounding encrypted-input size stay with the caller.
130
+
131
+ - **Keys** must be 32 uniformly random bytes. Passwords are not valid keys.
132
+ - **Nonces** come from `os.urandom(12)` per seal. AES-GCM-SIV tolerates reuse better than most modes, but do not reuse them.
133
+ - **Compression oracles.** Sealed size reveals which suite won. Never compress secrets mixed with attacker-controlled input without application-level separation. Pass `compress=False` when in doubt.
134
+ - **Resource limits.** `max_output_size` bounds decompressed output. For untrusted input, also cap the encrypted bytes before calling `open_data`.
135
+
136
+ This is an implementation with conformance vectors and tamper coverage, not an external audit.
137
+
138
+ ## Development
139
+
140
+ ```bash
141
+ uv sync --locked --extra dev
142
+ uv run ruff check .
143
+ uv run mypy kransx
144
+ uv run pytest -q
145
+ ```
146
+
147
+ Layout: `kransx/` holds seal, open, dicts, cli. `tests/` holds conformance vectors, tamper checks, resource limits. `bench/` holds the claim gates and their result snapshots.
148
+
149
+ ## License
150
+
151
+ MIT — see [LICENSE](LICENSE).
152
+
153
+ ## Changelog
154
+
155
+ See [CHANGELOG.md](CHANGELOG.md).
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "kransx"
7
- version = "0.2.0"
7
+ version = "0.2.1"
8
8
  description = "KRANSX authenticated encryption-envelope reference implementation"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.10"
kransx-0.2.0/PKG-INFO DELETED
@@ -1,163 +0,0 @@
1
- Metadata-Version: 2.4
2
- Name: kransx
3
- Version: 0.2.0
4
- Summary: KRANSX authenticated encryption-envelope reference implementation
5
- Author: KRANSX contributors
6
- License-Expression: MIT
7
- Keywords: aead,compression,encryption,zstandard
8
- Classifier: Development Status :: 3 - Alpha
9
- Classifier: Intended Audience :: Developers
10
- Classifier: Topic :: Security :: Cryptography
11
- Classifier: Topic :: System :: Archiving :: Compression
12
- Classifier: Programming Language :: Python :: 3
13
- Classifier: Programming Language :: Python :: 3.10
14
- Classifier: Programming Language :: Python :: 3.11
15
- Classifier: Programming Language :: Python :: 3.12
16
- Classifier: Programming Language :: Python :: 3.13
17
- Classifier: Programming Language :: Python :: 3.14
18
- Classifier: Operating System :: OS Independent
19
- Classifier: Typing :: Typed
20
- Requires-Python: >=3.10
21
- Description-Content-Type: text/markdown
22
- License-File: LICENSE
23
- Requires-Dist: cryptography>=42
24
- Requires-Dist: zstandard>=0.22
25
- Provides-Extra: dev
26
- Requires-Dist: mypy>=1.10; extra == "dev"
27
- Requires-Dist: pre-commit>=4; extra == "dev"
28
- Requires-Dist: pytest>=7; extra == "dev"
29
- Requires-Dist: ruff>=0.4; extra == "dev"
30
- Dynamic: license-file
31
-
32
- # KRANSX
33
-
34
- [![PyPI](https://img.shields.io/pypi/v/kransx.svg)](https://pypi.org/project/kransx/)
35
- [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org)
36
- [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
37
-
38
- Authenticated encryption with adaptive compression for Python.
39
-
40
- 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.
41
-
42
- ## Features
43
-
44
- - Adaptive compression — codec tournament (Zstandard at level and 19, LZMA-6) when beneficial, raw otherwise
45
- - Authenticated encryption — AES-256-GCM-SIV (nonce-misuse resistant)
46
- - Small fixed overhead — 29 bytes (`suite` + `nonce` + `tag`)
47
- - Simple API — `seal` / `open_data`, fully typed
48
- - Dictionary support — optional Zstandard dictionaries for structured data
49
- - CLI — `keygen`, `seal`, `open`, `train`, `bench`
50
- - No background services or async dependencies
51
-
52
- ## Installation
53
-
54
- ```bash
55
- pip install kransx
56
- ```
57
-
58
- For development:
59
-
60
- ```bash
61
- uv sync --locked --extra dev
62
- ```
63
-
64
- Requires Python 3.10+, `cryptography >= 42`, `zstandard >= 0.22`.
65
-
66
- ## Usage
67
-
68
- ### Python API
69
-
70
- ```python
71
- import secrets
72
- from kransx import open_data, seal
73
-
74
- key = secrets.token_bytes(32) # 32 uniformly random bytes
75
- aad = b"record-42" # associated data, authenticated but not encrypted
76
-
77
- sealed = seal(b"hello world", key, aad=aad)
78
- assert open_data(sealed, key, aad=aad) == b"hello world"
79
- ```
80
-
81
- Authentication failures raise `cryptography.exceptions.InvalidTag` (wrong key, AAD, dictionary, or modified bytes). Structural errors raise `ValueError`.
82
-
83
- With a shared dictionary (non-secret, improves compression on similar payloads):
84
-
85
- ```python
86
- from kransx import train_dict
87
-
88
- dictionary = train_dict([b'{"user":1,"action":"login"}'] * 300)
89
- sealed = seal(b'{"user":1,"action":"login"}', key, dict_obj=dictionary)
90
- assert open_data(sealed, key, dict_obj=dictionary) == b'{"user":1,"action":"login"}'
91
- ```
92
-
93
- API reference:
94
-
95
- ```python
96
- seal(data: bytes, key: bytes, *, dict_obj=None, aad=b"", compress=True, level=3) -> bytes
97
- open_data(blob: bytes, key: bytes, *, dict_obj=None, aad=b"", max_output_size=64*1024*1024) -> bytes
98
- train_dict(samples: Iterable[bytes], dict_size=16384) -> ZstdCompressionDict
99
- save_dict(dictionary, path) / load_dict(path)
100
- ```
101
-
102
- `compress=True` runs the codec tournament and keeps the strictly smallest payload; raw wins all ties. `max_output_size` limits the decompressed output size.
103
-
104
- ### CLI
105
-
106
- ```bash
107
- kransx keygen key.bin
108
- kransx seal plain.bin sealed.bin --key-file key.bin --aad 7265636f72642d3432
109
- kransx open sealed.bin restored.bin --key-file key.bin --aad 7265636f72642d3432
110
-
111
- kransx train 'samples/*.json' --output model.dict
112
- kransx seal plain.bin out.bin --key-file key.bin --dict model.dict
113
- kransx open out.bin restored.bin --key-file key.bin --dict model.dict --max-output-size 1048576
114
- kransx bench
115
- ```
116
-
117
- - `bench` runs the A+B claim gates (tournament bound, overhead floor); exit non-zero on failure
118
- - `--aad` accepts hex-encoded bytes
119
- - `--max-output-size` caps plaintext size on open
120
- - Output files are created exclusively and never overwritten
121
-
122
- ## Design
123
-
124
- Envelope layout: `suite (1) | nonce (12) | ciphertext | tag (16)`
125
-
126
- | Suite | Payload | Authenticated associated data |
127
- |-------|---------|-------------------------------|
128
- | `0x21` | Zstandard frame | `suite` + dictionary binding + `aad` |
129
- | `0x22` | raw bytes | `suite` + `aad` |
130
- | `0x23` | LZMA bytes (preset 6) | `suite` + no-dictionary binding + `aad` |
131
-
132
- - The dictionary binding is `SHA-256` over the dictionary bytes (or a constant for no dictionary), ensuring a mismatched dictionary fails authentication before decompression.
133
- - Keys are 32 random bytes expanded via HKDF-SHA256 to the AEAD key. A fresh 12-byte nonce is generated per seal.
134
- - Opening validates the envelope before decryption: size and suite checks, then AEAD authentication, then — for compressed payloads — single-frame Zstandard validation and bounded decompression.
135
-
136
- ## Security considerations
137
-
138
- This library implements the envelope only. Key generation, distribution, storage, rotation, and encrypted-input size bounding are the caller's responsibility.
139
-
140
- - **Keys** must be 32 uniformly random bytes. Passwords are not valid keys.
141
- - **Nonces** are generated with `os.urandom(12)` per seal. AES-GCM-SIV is nonce-misuse resistant, but reuse should still be avoided.
142
- - **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.
143
- - **Resource limits** — `max_output_size` bounds decompressed output. For untrusted inputs, also bound the encrypted input size before calling `open_data`.
144
-
145
- ## Development
146
-
147
- ```bash
148
- uv sync --locked --extra dev
149
- uv run ruff check .
150
- uv run mypy kransx
151
- uv run pytest -q
152
- ```
153
-
154
- Pre-commit hooks are configured for `ruff` and `mypy` (see `.pre-commit-config.yaml`).
155
-
156
- ```
157
- kransx/ seal, open_data, dicts, cli
158
- tests/ conformance vectors, tamper checks, resource limits
159
- ```
160
-
161
- ## License
162
-
163
- MIT — see [LICENSE](LICENSE).
kransx-0.2.0/README.md DELETED
@@ -1,132 +0,0 @@
1
- # KRANSX
2
-
3
- [![PyPI](https://img.shields.io/pypi/v/kransx.svg)](https://pypi.org/project/kransx/)
4
- [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org)
5
- [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
6
-
7
- Authenticated encryption with adaptive compression for Python.
8
-
9
- 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.
10
-
11
- ## Features
12
-
13
- - Adaptive compression — codec tournament (Zstandard at level and 19, LZMA-6) when beneficial, raw otherwise
14
- - Authenticated encryption — AES-256-GCM-SIV (nonce-misuse resistant)
15
- - Small fixed overhead — 29 bytes (`suite` + `nonce` + `tag`)
16
- - Simple API — `seal` / `open_data`, fully typed
17
- - Dictionary support — optional Zstandard dictionaries for structured data
18
- - CLI — `keygen`, `seal`, `open`, `train`, `bench`
19
- - No background services or async dependencies
20
-
21
- ## Installation
22
-
23
- ```bash
24
- pip install kransx
25
- ```
26
-
27
- For development:
28
-
29
- ```bash
30
- uv sync --locked --extra dev
31
- ```
32
-
33
- Requires Python 3.10+, `cryptography >= 42`, `zstandard >= 0.22`.
34
-
35
- ## Usage
36
-
37
- ### Python API
38
-
39
- ```python
40
- import secrets
41
- from kransx import open_data, seal
42
-
43
- key = secrets.token_bytes(32) # 32 uniformly random bytes
44
- aad = b"record-42" # associated data, authenticated but not encrypted
45
-
46
- sealed = seal(b"hello world", key, aad=aad)
47
- assert open_data(sealed, key, aad=aad) == b"hello world"
48
- ```
49
-
50
- Authentication failures raise `cryptography.exceptions.InvalidTag` (wrong key, AAD, dictionary, or modified bytes). Structural errors raise `ValueError`.
51
-
52
- With a shared dictionary (non-secret, improves compression on similar payloads):
53
-
54
- ```python
55
- from kransx import train_dict
56
-
57
- dictionary = train_dict([b'{"user":1,"action":"login"}'] * 300)
58
- sealed = seal(b'{"user":1,"action":"login"}', key, dict_obj=dictionary)
59
- assert open_data(sealed, key, dict_obj=dictionary) == b'{"user":1,"action":"login"}'
60
- ```
61
-
62
- API reference:
63
-
64
- ```python
65
- seal(data: bytes, key: bytes, *, dict_obj=None, aad=b"", compress=True, level=3) -> bytes
66
- open_data(blob: bytes, key: bytes, *, dict_obj=None, aad=b"", max_output_size=64*1024*1024) -> bytes
67
- train_dict(samples: Iterable[bytes], dict_size=16384) -> ZstdCompressionDict
68
- save_dict(dictionary, path) / load_dict(path)
69
- ```
70
-
71
- `compress=True` runs the codec tournament and keeps the strictly smallest payload; raw wins all ties. `max_output_size` limits the decompressed output size.
72
-
73
- ### CLI
74
-
75
- ```bash
76
- kransx keygen key.bin
77
- kransx seal plain.bin sealed.bin --key-file key.bin --aad 7265636f72642d3432
78
- kransx open sealed.bin restored.bin --key-file key.bin --aad 7265636f72642d3432
79
-
80
- kransx train 'samples/*.json' --output model.dict
81
- kransx seal plain.bin out.bin --key-file key.bin --dict model.dict
82
- kransx open out.bin restored.bin --key-file key.bin --dict model.dict --max-output-size 1048576
83
- kransx bench
84
- ```
85
-
86
- - `bench` runs the A+B claim gates (tournament bound, overhead floor); exit non-zero on failure
87
- - `--aad` accepts hex-encoded bytes
88
- - `--max-output-size` caps plaintext size on open
89
- - Output files are created exclusively and never overwritten
90
-
91
- ## Design
92
-
93
- Envelope layout: `suite (1) | nonce (12) | ciphertext | tag (16)`
94
-
95
- | Suite | Payload | Authenticated associated data |
96
- |-------|---------|-------------------------------|
97
- | `0x21` | Zstandard frame | `suite` + dictionary binding + `aad` |
98
- | `0x22` | raw bytes | `suite` + `aad` |
99
- | `0x23` | LZMA bytes (preset 6) | `suite` + no-dictionary binding + `aad` |
100
-
101
- - The dictionary binding is `SHA-256` over the dictionary bytes (or a constant for no dictionary), ensuring a mismatched dictionary fails authentication before decompression.
102
- - Keys are 32 random bytes expanded via HKDF-SHA256 to the AEAD key. A fresh 12-byte nonce is generated per seal.
103
- - Opening validates the envelope before decryption: size and suite checks, then AEAD authentication, then — for compressed payloads — single-frame Zstandard validation and bounded decompression.
104
-
105
- ## Security considerations
106
-
107
- This library implements the envelope only. Key generation, distribution, storage, rotation, and encrypted-input size bounding are the caller's responsibility.
108
-
109
- - **Keys** must be 32 uniformly random bytes. Passwords are not valid keys.
110
- - **Nonces** are generated with `os.urandom(12)` per seal. AES-GCM-SIV is nonce-misuse resistant, but reuse should still be avoided.
111
- - **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.
112
- - **Resource limits** — `max_output_size` bounds decompressed output. For untrusted inputs, also bound the encrypted input size before calling `open_data`.
113
-
114
- ## Development
115
-
116
- ```bash
117
- uv sync --locked --extra dev
118
- uv run ruff check .
119
- uv run mypy kransx
120
- uv run pytest -q
121
- ```
122
-
123
- Pre-commit hooks are configured for `ruff` and `mypy` (see `.pre-commit-config.yaml`).
124
-
125
- ```
126
- kransx/ seal, open_data, dicts, cli
127
- tests/ conformance vectors, tamper checks, resource limits
128
- ```
129
-
130
- ## License
131
-
132
- MIT — see [LICENSE](LICENSE).
@@ -1,163 +0,0 @@
1
- Metadata-Version: 2.4
2
- Name: kransx
3
- Version: 0.2.0
4
- Summary: KRANSX authenticated encryption-envelope reference implementation
5
- Author: KRANSX contributors
6
- License-Expression: MIT
7
- Keywords: aead,compression,encryption,zstandard
8
- Classifier: Development Status :: 3 - Alpha
9
- Classifier: Intended Audience :: Developers
10
- Classifier: Topic :: Security :: Cryptography
11
- Classifier: Topic :: System :: Archiving :: Compression
12
- Classifier: Programming Language :: Python :: 3
13
- Classifier: Programming Language :: Python :: 3.10
14
- Classifier: Programming Language :: Python :: 3.11
15
- Classifier: Programming Language :: Python :: 3.12
16
- Classifier: Programming Language :: Python :: 3.13
17
- Classifier: Programming Language :: Python :: 3.14
18
- Classifier: Operating System :: OS Independent
19
- Classifier: Typing :: Typed
20
- Requires-Python: >=3.10
21
- Description-Content-Type: text/markdown
22
- License-File: LICENSE
23
- Requires-Dist: cryptography>=42
24
- Requires-Dist: zstandard>=0.22
25
- Provides-Extra: dev
26
- Requires-Dist: mypy>=1.10; extra == "dev"
27
- Requires-Dist: pre-commit>=4; extra == "dev"
28
- Requires-Dist: pytest>=7; extra == "dev"
29
- Requires-Dist: ruff>=0.4; extra == "dev"
30
- Dynamic: license-file
31
-
32
- # KRANSX
33
-
34
- [![PyPI](https://img.shields.io/pypi/v/kransx.svg)](https://pypi.org/project/kransx/)
35
- [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org)
36
- [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
37
-
38
- Authenticated encryption with adaptive compression for Python.
39
-
40
- 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.
41
-
42
- ## Features
43
-
44
- - Adaptive compression — codec tournament (Zstandard at level and 19, LZMA-6) when beneficial, raw otherwise
45
- - Authenticated encryption — AES-256-GCM-SIV (nonce-misuse resistant)
46
- - Small fixed overhead — 29 bytes (`suite` + `nonce` + `tag`)
47
- - Simple API — `seal` / `open_data`, fully typed
48
- - Dictionary support — optional Zstandard dictionaries for structured data
49
- - CLI — `keygen`, `seal`, `open`, `train`, `bench`
50
- - No background services or async dependencies
51
-
52
- ## Installation
53
-
54
- ```bash
55
- pip install kransx
56
- ```
57
-
58
- For development:
59
-
60
- ```bash
61
- uv sync --locked --extra dev
62
- ```
63
-
64
- Requires Python 3.10+, `cryptography >= 42`, `zstandard >= 0.22`.
65
-
66
- ## Usage
67
-
68
- ### Python API
69
-
70
- ```python
71
- import secrets
72
- from kransx import open_data, seal
73
-
74
- key = secrets.token_bytes(32) # 32 uniformly random bytes
75
- aad = b"record-42" # associated data, authenticated but not encrypted
76
-
77
- sealed = seal(b"hello world", key, aad=aad)
78
- assert open_data(sealed, key, aad=aad) == b"hello world"
79
- ```
80
-
81
- Authentication failures raise `cryptography.exceptions.InvalidTag` (wrong key, AAD, dictionary, or modified bytes). Structural errors raise `ValueError`.
82
-
83
- With a shared dictionary (non-secret, improves compression on similar payloads):
84
-
85
- ```python
86
- from kransx import train_dict
87
-
88
- dictionary = train_dict([b'{"user":1,"action":"login"}'] * 300)
89
- sealed = seal(b'{"user":1,"action":"login"}', key, dict_obj=dictionary)
90
- assert open_data(sealed, key, dict_obj=dictionary) == b'{"user":1,"action":"login"}'
91
- ```
92
-
93
- API reference:
94
-
95
- ```python
96
- seal(data: bytes, key: bytes, *, dict_obj=None, aad=b"", compress=True, level=3) -> bytes
97
- open_data(blob: bytes, key: bytes, *, dict_obj=None, aad=b"", max_output_size=64*1024*1024) -> bytes
98
- train_dict(samples: Iterable[bytes], dict_size=16384) -> ZstdCompressionDict
99
- save_dict(dictionary, path) / load_dict(path)
100
- ```
101
-
102
- `compress=True` runs the codec tournament and keeps the strictly smallest payload; raw wins all ties. `max_output_size` limits the decompressed output size.
103
-
104
- ### CLI
105
-
106
- ```bash
107
- kransx keygen key.bin
108
- kransx seal plain.bin sealed.bin --key-file key.bin --aad 7265636f72642d3432
109
- kransx open sealed.bin restored.bin --key-file key.bin --aad 7265636f72642d3432
110
-
111
- kransx train 'samples/*.json' --output model.dict
112
- kransx seal plain.bin out.bin --key-file key.bin --dict model.dict
113
- kransx open out.bin restored.bin --key-file key.bin --dict model.dict --max-output-size 1048576
114
- kransx bench
115
- ```
116
-
117
- - `bench` runs the A+B claim gates (tournament bound, overhead floor); exit non-zero on failure
118
- - `--aad` accepts hex-encoded bytes
119
- - `--max-output-size` caps plaintext size on open
120
- - Output files are created exclusively and never overwritten
121
-
122
- ## Design
123
-
124
- Envelope layout: `suite (1) | nonce (12) | ciphertext | tag (16)`
125
-
126
- | Suite | Payload | Authenticated associated data |
127
- |-------|---------|-------------------------------|
128
- | `0x21` | Zstandard frame | `suite` + dictionary binding + `aad` |
129
- | `0x22` | raw bytes | `suite` + `aad` |
130
- | `0x23` | LZMA bytes (preset 6) | `suite` + no-dictionary binding + `aad` |
131
-
132
- - The dictionary binding is `SHA-256` over the dictionary bytes (or a constant for no dictionary), ensuring a mismatched dictionary fails authentication before decompression.
133
- - Keys are 32 random bytes expanded via HKDF-SHA256 to the AEAD key. A fresh 12-byte nonce is generated per seal.
134
- - Opening validates the envelope before decryption: size and suite checks, then AEAD authentication, then — for compressed payloads — single-frame Zstandard validation and bounded decompression.
135
-
136
- ## Security considerations
137
-
138
- This library implements the envelope only. Key generation, distribution, storage, rotation, and encrypted-input size bounding are the caller's responsibility.
139
-
140
- - **Keys** must be 32 uniformly random bytes. Passwords are not valid keys.
141
- - **Nonces** are generated with `os.urandom(12)` per seal. AES-GCM-SIV is nonce-misuse resistant, but reuse should still be avoided.
142
- - **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.
143
- - **Resource limits** — `max_output_size` bounds decompressed output. For untrusted inputs, also bound the encrypted input size before calling `open_data`.
144
-
145
- ## Development
146
-
147
- ```bash
148
- uv sync --locked --extra dev
149
- uv run ruff check .
150
- uv run mypy kransx
151
- uv run pytest -q
152
- ```
153
-
154
- Pre-commit hooks are configured for `ruff` and `mypy` (see `.pre-commit-config.yaml`).
155
-
156
- ```
157
- kransx/ seal, open_data, dicts, cli
158
- tests/ conformance vectors, tamper checks, resource limits
159
- ```
160
-
161
- ## License
162
-
163
- MIT — see [LICENSE](LICENSE).
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes