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 +155 -0
- kransx-0.2.1/README.md +124 -0
- {kransx-0.2.0 → kransx-0.2.1}/kransx/__init__.py +1 -1
- {kransx-0.2.0 → kransx-0.2.1}/kransx/core.py +7 -6
- kransx-0.2.1/kransx.egg-info/PKG-INFO +155 -0
- {kransx-0.2.0 → kransx-0.2.1}/pyproject.toml +1 -1
- kransx-0.2.0/PKG-INFO +0 -163
- kransx-0.2.0/README.md +0 -132
- kransx-0.2.0/kransx.egg-info/PKG-INFO +0 -163
- {kransx-0.2.0 → kransx-0.2.1}/LICENSE +0 -0
- {kransx-0.2.0 → kransx-0.2.1}/kransx/cli.py +0 -0
- {kransx-0.2.0 → kransx-0.2.1}/kransx/dicts.py +0 -0
- {kransx-0.2.0 → kransx-0.2.1}/kransx/py.typed +0 -0
- {kransx-0.2.0 → kransx-0.2.1}/kransx.egg-info/SOURCES.txt +0 -0
- {kransx-0.2.0 → kransx-0.2.1}/kransx.egg-info/dependency_links.txt +0 -0
- {kransx-0.2.0 → kransx-0.2.1}/kransx.egg-info/entry_points.txt +0 -0
- {kransx-0.2.0 → kransx-0.2.1}/kransx.egg-info/requires.txt +0 -0
- {kransx-0.2.0 → kransx-0.2.1}/kransx.egg-info/top_level.txt +0 -0
- {kransx-0.2.0 → kransx-0.2.1}/setup.cfg +0 -0
- {kransx-0.2.0 → kransx-0.2.1}/tests/test_kransx.py +0 -0
- {kransx-0.2.0 → kransx-0.2.1}/tests/test_v02.py +0 -0
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
|
+
[](https://pypi.org/project/kransx/)
|
|
35
|
+
[](https://www.python.org)
|
|
36
|
+
[](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
|
+
[](https://pypi.org/project/kransx/)
|
|
4
|
+
[](https://www.python.org)
|
|
5
|
+
[](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).
|
|
@@ -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
|
-
|
|
61
|
-
)
|
|
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=
|
|
113
|
-
|
|
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
|
+
[](https://pypi.org/project/kransx/)
|
|
35
|
+
[](https://www.python.org)
|
|
36
|
+
[](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.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
|
-
[](https://pypi.org/project/kransx/)
|
|
35
|
-
[](https://www.python.org)
|
|
36
|
-
[](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
|
-
[](https://pypi.org/project/kransx/)
|
|
4
|
-
[](https://www.python.org)
|
|
5
|
-
[](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
|
-
[](https://pypi.org/project/kransx/)
|
|
35
|
-
[](https://www.python.org)
|
|
36
|
-
[](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
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|