b53 0.1.0__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.
- b53-0.1.0/.gitignore +25 -0
- b53-0.1.0/LICENSE +21 -0
- b53-0.1.0/PKG-INFO +158 -0
- b53-0.1.0/README.md +124 -0
- b53-0.1.0/README_RU.md +110 -0
- b53-0.1.0/pyproject.toml +93 -0
- b53-0.1.0/src/b53/__init__.py +54 -0
- b53-0.1.0/src/b53/__main__.py +8 -0
- b53-0.1.0/src/b53/cli.py +162 -0
- b53-0.1.0/src/b53/core.py +287 -0
- b53-0.1.0/src/b53/py.typed +0 -0
- b53-0.1.0/tests/test_cli.py +85 -0
- b53-0.1.0/tests/test_core.py +232 -0
- b53-0.1.0/tests/test_partition.py +42 -0
- b53-0.1.0/tests/test_vectors.py +85 -0
b53-0.1.0/.gitignore
ADDED
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# Python
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
*$py.class
|
|
5
|
+
*.egg-info/
|
|
6
|
+
.eggs/
|
|
7
|
+
build/
|
|
8
|
+
dist/
|
|
9
|
+
|
|
10
|
+
# Virtual environments
|
|
11
|
+
.venv/
|
|
12
|
+
venv/
|
|
13
|
+
ENV/
|
|
14
|
+
|
|
15
|
+
# Testing & linters
|
|
16
|
+
.pytest_cache/
|
|
17
|
+
.mypy_cache/
|
|
18
|
+
.ruff_cache/
|
|
19
|
+
.coverage
|
|
20
|
+
htmlcov/
|
|
21
|
+
|
|
22
|
+
# OS / Editors
|
|
23
|
+
.DS_Store
|
|
24
|
+
.idea/
|
|
25
|
+
.vscode/
|
b53-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 1orgar
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
b53-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,158 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: b53
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Reversible 53-bit cryptographic packing of 1-50 booleans with hidden length and random nonce into an IEEE 754 double in [0.0, 1.0)
|
|
5
|
+
Project-URL: Homepage, https://github.com/1orgar/b53
|
|
6
|
+
Project-URL: Repository, https://github.com/1orgar/b53
|
|
7
|
+
Project-URL: Issues, https://github.com/1orgar/b53/issues
|
|
8
|
+
Author: 1orgar
|
|
9
|
+
License-Expression: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: bit-packing,boolean,cipher,double,encryption,feistel,format-preserving,hmac-sha256,ieee754
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Intended Audience :: Science/Research
|
|
15
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
16
|
+
Classifier: Operating System :: OS Independent
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
23
|
+
Classifier: Topic :: Security :: Cryptography
|
|
24
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
25
|
+
Classifier: Typing :: Typed
|
|
26
|
+
Requires-Python: >=3.10
|
|
27
|
+
Provides-Extra: dev
|
|
28
|
+
Requires-Dist: build>=1.2; extra == 'dev'
|
|
29
|
+
Requires-Dist: mypy>=1.11; extra == 'dev'
|
|
30
|
+
Requires-Dist: pytest>=8.0; extra == 'dev'
|
|
31
|
+
Requires-Dist: ruff>=0.8; extra == 'dev'
|
|
32
|
+
Requires-Dist: twine>=6.1; extra == 'dev'
|
|
33
|
+
Description-Content-Type: text/markdown
|
|
34
|
+
|
|
35
|
+
# b53
|
|
36
|
+
|
|
37
|
+
**English** | [🇷🇺 Русская версия](README_RU.md)
|
|
38
|
+
|
|
39
|
+
[](https://pypi.org/project/b53/)
|
|
40
|
+
[](https://pypi.org/project/b53/)
|
|
41
|
+
[](https://opensource.org/licenses/MIT)
|
|
42
|
+
[](https://github.com/1orgar/b53/actions/workflows/ci.yml)
|
|
43
|
+
|
|
44
|
+
**`b53`** is a zero-dependency Python library for reversible cryptographic packing of boolean arrays of arbitrary length $L \in [1, 50]$ into a single standard IEEE 754 `binary64` (`double` / Python `float`) in the half-open interval $[0.0, 1.0)$.
|
|
45
|
+
|
|
46
|
+
## Key Properties
|
|
47
|
+
|
|
48
|
+
- **Hidden length inside the float:** the original array length $L \in [1, 50]$ is encoded directly inside the 53-bit mantissa space—no external length metadata is required.
|
|
49
|
+
- **Randomized output (nonce) per encryption:** encrypting the same boolean array with the same salt produces different pseudorandom doubles in $[0.0, 1.0)$.
|
|
50
|
+
- **Bijective 53-bit permutation:** uses an 8-round unbalanced Feistel network ($26 + 27 = 53$ bits) keyed by `HMAC-SHA256` with your secret salt.
|
|
51
|
+
- **Pure Python standard library:** zero runtime dependencies, typed (`py.typed`), Python 3.10+.
|
|
52
|
+
|
|
53
|
+
## Installation
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
pip install b53
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
## Quick Start
|
|
60
|
+
|
|
61
|
+
### Python API
|
|
62
|
+
|
|
63
|
+
```python
|
|
64
|
+
import b53
|
|
65
|
+
|
|
66
|
+
# 1. Generate a 256-bit secret salt (store securely)
|
|
67
|
+
salt = b53.generate_salt()
|
|
68
|
+
|
|
69
|
+
# 2. Encrypt a boolean array (1..50 elements) into a float in [0.0, 1.0)
|
|
70
|
+
bits = [True, False, True, True, False, False, True, False, True, True]
|
|
71
|
+
x1 = b53.encrypt(bits, salt)
|
|
72
|
+
x2 = b53.encrypt(bits, salt) # different float due to random nonce
|
|
73
|
+
assert x1 != x2
|
|
74
|
+
|
|
75
|
+
# 3. Decrypt back to the exact original list[bool] and length
|
|
76
|
+
assert b53.decrypt(x1, salt) == bits
|
|
77
|
+
assert b53.decrypt(x2, salt) == bits
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
For repeated operations with the same salt, use `B53Cipher` (alias `Cipher`):
|
|
81
|
+
|
|
82
|
+
```python
|
|
83
|
+
from b53 import B53Cipher
|
|
84
|
+
|
|
85
|
+
cipher = B53Cipher(salt)
|
|
86
|
+
encoded = cipher.encrypt_str("1011001011")
|
|
87
|
+
print(repr(encoded))
|
|
88
|
+
print(cipher.decrypt_str(encoded)) # "1011001011"
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
### Command-Line Interface
|
|
92
|
+
|
|
93
|
+
```bash
|
|
94
|
+
# 1. Generate a 256-bit hex salt
|
|
95
|
+
SALT=$(b53 generate-salt)
|
|
96
|
+
|
|
97
|
+
# 2. Encrypt the same bit string 3 times
|
|
98
|
+
b53 encrypt 1011001011 --salt "$SALT" --count 3
|
|
99
|
+
|
|
100
|
+
# 3. Decrypt any generated double back to the original array
|
|
101
|
+
b53 decrypt 0.7419283058129402 --salt "$SALT"
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
You can also run via `python -m b53 ...`, pass `--salt-file path/to/salt`, or set the `B53_SALT` environment variable.
|
|
105
|
+
|
|
106
|
+
## How It Works
|
|
107
|
+
|
|
108
|
+
An IEEE 754 `binary64` float on the uniform $2^{-53}$ grid represents $x = C \cdot 2^{-53}$ for $C \in \{0, 1, \dots, 2^{53} - 1\}$.
|
|
109
|
+
|
|
110
|
+
The entire 53-bit state space ($2^{53} = 9\,007\,199\,254\,740\,992$ states) is partitioned without gaps or overlaps across all 50 lengths $L \in [1, 50]$ so that:
|
|
111
|
+
|
|
112
|
+
$$\sum_{L=1}^{50} M_L \cdot 2^L = 2^{53}$$
|
|
113
|
+
|
|
114
|
+
Space is allocated top-down from $L = 50$ to $L = 1$, reserving $\approx 25\%$ of the remaining budget at each step (at least $M_L \ge 3$ nonces even at $L = 50$):
|
|
115
|
+
|
|
116
|
+
| Length $L$ | Data combinations ($2^L$) | Nonces per array ($M_L$) | Segment size ($M_L \cdot 2^L$) |
|
|
117
|
+
|---:|---:|---:|---:|
|
|
118
|
+
| 50 | $2^{50}$ | 3 | $3 \times 2^{50}$ |
|
|
119
|
+
| 49 | $2^{49}$ | 3 | $3 \times 2^{49}$ |
|
|
120
|
+
| 48 | $2^{48}$ | 3 | $3 \times 2^{48}$ |
|
|
121
|
+
| 47 | $2^{47}$ | 5 | $5 \times 2^{47}$ |
|
|
122
|
+
| 45 | $2^{45}$ | 13 | $13 \times 2^{45}$ |
|
|
123
|
+
| 40 | $2^{40}$ | 100 | $100 \times 2^{40}$ |
|
|
124
|
+
| 30 | $2^{30}$ | 5,811 | $5{,}811 \times 2^{30}$ |
|
|
125
|
+
| 20 | $2^{20}$ | 335,103 | $335{,}103 \times 2^{20}$ |
|
|
126
|
+
| 10 | $2^{10}$ | 19,323,738 | $\approx 1.98 \times 10^{10}$ |
|
|
127
|
+
| 1 | $2^1$ | 2,971,477,630 | $\approx 5.94 \times 10^{9}$ |
|
|
128
|
+
|
|
129
|
+
1. **Pack:** encode `bits` as $D \in [0, 2^L - 1]$, pick $r \in [0, M_L - 1]$ via `secrets.randbelow`, and compute $P = \text{BASE}[L] + r \cdot 2^L + D$.
|
|
130
|
+
2. **Permute:** apply an 8-round unbalanced Feistel network ($26 + 27$ bits) with `HMAC-SHA256` keyed by the normalized salt to obtain $C \in [0, 2^{53} - 1]$.
|
|
131
|
+
3. **Float conversion:** return `math.ldexp(C, -53)` ($C \cdot 2^{-53}$).
|
|
132
|
+
4. **Decrypt:** verify $x \in [0.0, 1.0)$ lies exactly on the $2^{-53}$ grid, invert the Feistel permutation to recover $P$, find the unique range $L$, discard $r$, and unpack the lower $L$ bits of $P - \text{BASE}[L]$.
|
|
133
|
+
|
|
134
|
+
## Precision Requirements
|
|
135
|
+
|
|
136
|
+
When serializing the encrypted `double` to text, JSON, CSV, or CLI arguments, always preserve all significant binary64 digits using `repr(x)` / `f"{x:.17g}"` (or native `DOUBLE PRECISION` / `FLOAT8` in databases). Rounding even the least significant digit alters the lower bits of the 53-bit ciphertext and breaks decryption.
|
|
137
|
+
|
|
138
|
+
## API Reference
|
|
139
|
+
|
|
140
|
+
- `generate_salt(num_bytes: int = 32) -> str` — generate a cryptographically random hex salt ($\ge 16$ bytes).
|
|
141
|
+
- `encrypt(bits, salt) -> float` / `encrypt_bool_array(bits, salt) -> float` — encrypt $1..50$ booleans (or `0`/`1` ints) into a double in $[0.0, 1.0)$.
|
|
142
|
+
- `decrypt(double_val, salt) -> list[bool]` / `decrypt_bool_array(double_val, salt) -> list[bool]` — recover the exact boolean list and length.
|
|
143
|
+
- `parse_bits(raw: str) -> list[bool]` — parse `"10110"` or `"true,false,1,0"`.
|
|
144
|
+
- `format_bits(bits) -> str` — format booleans as `"10110"`.
|
|
145
|
+
- `B53Cipher(salt)` (alias `Cipher`) — reusable cipher object with `.encrypt()`, `.decrypt()`, `.encrypt_str()`, `.decrypt_str()`, and `B53Cipher.generate()`.
|
|
146
|
+
|
|
147
|
+
## Development
|
|
148
|
+
|
|
149
|
+
```bash
|
|
150
|
+
pip install -e ".[dev]"
|
|
151
|
+
pytest
|
|
152
|
+
ruff check src tests
|
|
153
|
+
mypy src
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
## License
|
|
157
|
+
|
|
158
|
+
[MIT](LICENSE)
|
b53-0.1.0/README.md
ADDED
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
# b53
|
|
2
|
+
|
|
3
|
+
**English** | [🇷🇺 Русская версия](README_RU.md)
|
|
4
|
+
|
|
5
|
+
[](https://pypi.org/project/b53/)
|
|
6
|
+
[](https://pypi.org/project/b53/)
|
|
7
|
+
[](https://opensource.org/licenses/MIT)
|
|
8
|
+
[](https://github.com/1orgar/b53/actions/workflows/ci.yml)
|
|
9
|
+
|
|
10
|
+
**`b53`** is a zero-dependency Python library for reversible cryptographic packing of boolean arrays of arbitrary length $L \in [1, 50]$ into a single standard IEEE 754 `binary64` (`double` / Python `float`) in the half-open interval $[0.0, 1.0)$.
|
|
11
|
+
|
|
12
|
+
## Key Properties
|
|
13
|
+
|
|
14
|
+
- **Hidden length inside the float:** the original array length $L \in [1, 50]$ is encoded directly inside the 53-bit mantissa space—no external length metadata is required.
|
|
15
|
+
- **Randomized output (nonce) per encryption:** encrypting the same boolean array with the same salt produces different pseudorandom doubles in $[0.0, 1.0)$.
|
|
16
|
+
- **Bijective 53-bit permutation:** uses an 8-round unbalanced Feistel network ($26 + 27 = 53$ bits) keyed by `HMAC-SHA256` with your secret salt.
|
|
17
|
+
- **Pure Python standard library:** zero runtime dependencies, typed (`py.typed`), Python 3.10+.
|
|
18
|
+
|
|
19
|
+
## Installation
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
pip install b53
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
## Quick Start
|
|
26
|
+
|
|
27
|
+
### Python API
|
|
28
|
+
|
|
29
|
+
```python
|
|
30
|
+
import b53
|
|
31
|
+
|
|
32
|
+
# 1. Generate a 256-bit secret salt (store securely)
|
|
33
|
+
salt = b53.generate_salt()
|
|
34
|
+
|
|
35
|
+
# 2. Encrypt a boolean array (1..50 elements) into a float in [0.0, 1.0)
|
|
36
|
+
bits = [True, False, True, True, False, False, True, False, True, True]
|
|
37
|
+
x1 = b53.encrypt(bits, salt)
|
|
38
|
+
x2 = b53.encrypt(bits, salt) # different float due to random nonce
|
|
39
|
+
assert x1 != x2
|
|
40
|
+
|
|
41
|
+
# 3. Decrypt back to the exact original list[bool] and length
|
|
42
|
+
assert b53.decrypt(x1, salt) == bits
|
|
43
|
+
assert b53.decrypt(x2, salt) == bits
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
For repeated operations with the same salt, use `B53Cipher` (alias `Cipher`):
|
|
47
|
+
|
|
48
|
+
```python
|
|
49
|
+
from b53 import B53Cipher
|
|
50
|
+
|
|
51
|
+
cipher = B53Cipher(salt)
|
|
52
|
+
encoded = cipher.encrypt_str("1011001011")
|
|
53
|
+
print(repr(encoded))
|
|
54
|
+
print(cipher.decrypt_str(encoded)) # "1011001011"
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
### Command-Line Interface
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
# 1. Generate a 256-bit hex salt
|
|
61
|
+
SALT=$(b53 generate-salt)
|
|
62
|
+
|
|
63
|
+
# 2. Encrypt the same bit string 3 times
|
|
64
|
+
b53 encrypt 1011001011 --salt "$SALT" --count 3
|
|
65
|
+
|
|
66
|
+
# 3. Decrypt any generated double back to the original array
|
|
67
|
+
b53 decrypt 0.7419283058129402 --salt "$SALT"
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
You can also run via `python -m b53 ...`, pass `--salt-file path/to/salt`, or set the `B53_SALT` environment variable.
|
|
71
|
+
|
|
72
|
+
## How It Works
|
|
73
|
+
|
|
74
|
+
An IEEE 754 `binary64` float on the uniform $2^{-53}$ grid represents $x = C \cdot 2^{-53}$ for $C \in \{0, 1, \dots, 2^{53} - 1\}$.
|
|
75
|
+
|
|
76
|
+
The entire 53-bit state space ($2^{53} = 9\,007\,199\,254\,740\,992$ states) is partitioned without gaps or overlaps across all 50 lengths $L \in [1, 50]$ so that:
|
|
77
|
+
|
|
78
|
+
$$\sum_{L=1}^{50} M_L \cdot 2^L = 2^{53}$$
|
|
79
|
+
|
|
80
|
+
Space is allocated top-down from $L = 50$ to $L = 1$, reserving $\approx 25\%$ of the remaining budget at each step (at least $M_L \ge 3$ nonces even at $L = 50$):
|
|
81
|
+
|
|
82
|
+
| Length $L$ | Data combinations ($2^L$) | Nonces per array ($M_L$) | Segment size ($M_L \cdot 2^L$) |
|
|
83
|
+
|---:|---:|---:|---:|
|
|
84
|
+
| 50 | $2^{50}$ | 3 | $3 \times 2^{50}$ |
|
|
85
|
+
| 49 | $2^{49}$ | 3 | $3 \times 2^{49}$ |
|
|
86
|
+
| 48 | $2^{48}$ | 3 | $3 \times 2^{48}$ |
|
|
87
|
+
| 47 | $2^{47}$ | 5 | $5 \times 2^{47}$ |
|
|
88
|
+
| 45 | $2^{45}$ | 13 | $13 \times 2^{45}$ |
|
|
89
|
+
| 40 | $2^{40}$ | 100 | $100 \times 2^{40}$ |
|
|
90
|
+
| 30 | $2^{30}$ | 5,811 | $5{,}811 \times 2^{30}$ |
|
|
91
|
+
| 20 | $2^{20}$ | 335,103 | $335{,}103 \times 2^{20}$ |
|
|
92
|
+
| 10 | $2^{10}$ | 19,323,738 | $\approx 1.98 \times 10^{10}$ |
|
|
93
|
+
| 1 | $2^1$ | 2,971,477,630 | $\approx 5.94 \times 10^{9}$ |
|
|
94
|
+
|
|
95
|
+
1. **Pack:** encode `bits` as $D \in [0, 2^L - 1]$, pick $r \in [0, M_L - 1]$ via `secrets.randbelow`, and compute $P = \text{BASE}[L] + r \cdot 2^L + D$.
|
|
96
|
+
2. **Permute:** apply an 8-round unbalanced Feistel network ($26 + 27$ bits) with `HMAC-SHA256` keyed by the normalized salt to obtain $C \in [0, 2^{53} - 1]$.
|
|
97
|
+
3. **Float conversion:** return `math.ldexp(C, -53)` ($C \cdot 2^{-53}$).
|
|
98
|
+
4. **Decrypt:** verify $x \in [0.0, 1.0)$ lies exactly on the $2^{-53}$ grid, invert the Feistel permutation to recover $P$, find the unique range $L$, discard $r$, and unpack the lower $L$ bits of $P - \text{BASE}[L]$.
|
|
99
|
+
|
|
100
|
+
## Precision Requirements
|
|
101
|
+
|
|
102
|
+
When serializing the encrypted `double` to text, JSON, CSV, or CLI arguments, always preserve all significant binary64 digits using `repr(x)` / `f"{x:.17g}"` (or native `DOUBLE PRECISION` / `FLOAT8` in databases). Rounding even the least significant digit alters the lower bits of the 53-bit ciphertext and breaks decryption.
|
|
103
|
+
|
|
104
|
+
## API Reference
|
|
105
|
+
|
|
106
|
+
- `generate_salt(num_bytes: int = 32) -> str` — generate a cryptographically random hex salt ($\ge 16$ bytes).
|
|
107
|
+
- `encrypt(bits, salt) -> float` / `encrypt_bool_array(bits, salt) -> float` — encrypt $1..50$ booleans (or `0`/`1` ints) into a double in $[0.0, 1.0)$.
|
|
108
|
+
- `decrypt(double_val, salt) -> list[bool]` / `decrypt_bool_array(double_val, salt) -> list[bool]` — recover the exact boolean list and length.
|
|
109
|
+
- `parse_bits(raw: str) -> list[bool]` — parse `"10110"` or `"true,false,1,0"`.
|
|
110
|
+
- `format_bits(bits) -> str` — format booleans as `"10110"`.
|
|
111
|
+
- `B53Cipher(salt)` (alias `Cipher`) — reusable cipher object with `.encrypt()`, `.decrypt()`, `.encrypt_str()`, `.decrypt_str()`, and `B53Cipher.generate()`.
|
|
112
|
+
|
|
113
|
+
## Development
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
pip install -e ".[dev]"
|
|
117
|
+
pytest
|
|
118
|
+
ruff check src tests
|
|
119
|
+
mypy src
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
## License
|
|
123
|
+
|
|
124
|
+
[MIT](LICENSE)
|
b53-0.1.0/README_RU.md
ADDED
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
# b53
|
|
2
|
+
|
|
3
|
+
[English](README.md) | **🇷🇺 Русская версия**
|
|
4
|
+
|
|
5
|
+
[](https://pypi.org/project/b53/)
|
|
6
|
+
[](https://pypi.org/project/b53/)
|
|
7
|
+
[](https://opensource.org/licenses/MIT)
|
|
8
|
+
[](https://github.com/1orgar/b53/actions/workflows/ci.yml)
|
|
9
|
+
|
|
10
|
+
**`b53`** — Python-библиотека без внешних зависимостей для обратимого криптографического шифрования булева массива произвольной длины $L \in [1, 50]$ в одно стандартное 64-битное число с плавающей точкой (`IEEE 754 binary64` / `double` / `float` в Python) на полуинтервале $[0.0, 1.0)$.
|
|
11
|
+
|
|
12
|
+
## Ключевые свойства
|
|
13
|
+
|
|
14
|
+
- **Скрытая размерность внутри числа:** длина массива $L \in [1, 50]$ кодируется непосредственно в 53-битном пространстве мантиссы без передачи внешних метаданных.
|
|
15
|
+
- **Случайная компонента (Nonce) при каждой генерации:** повторное шифрование одного и того же массива с одной и той же солью даёт разные псевдослучайные `double`.
|
|
16
|
+
- **Биективная 53-битная перестановка:** 8-раундовая несбалансированная сеть Фейстеля ($26 + 27 = 53$ бита) с раундовой функцией на базе `HMAC-SHA256` и секретной соли.
|
|
17
|
+
- **Только стандартная библиотека Python 3.10+:** ноль внешних зависимостей, полная типизация (`py.typed`).
|
|
18
|
+
|
|
19
|
+
## Установка
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
pip install b53
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
## Быстрый старт
|
|
26
|
+
|
|
27
|
+
### Python API
|
|
28
|
+
|
|
29
|
+
```python
|
|
30
|
+
import b53
|
|
31
|
+
|
|
32
|
+
# 1. Генерация 256-битной соли-ключа
|
|
33
|
+
salt = b53.generate_salt()
|
|
34
|
+
|
|
35
|
+
# 2. Шифрование массива bool (1..50 элементов) в double [0.0, 1.0)
|
|
36
|
+
bits = [True, False, True, True, False, False, True, False, True, True]
|
|
37
|
+
x1 = b53.encrypt(bits, salt)
|
|
38
|
+
x2 = b53.encrypt(bits, salt) # разный результат за счёт случайного nonce
|
|
39
|
+
assert x1 != x2
|
|
40
|
+
|
|
41
|
+
# 3. Однозначное восстановление массива и его длины
|
|
42
|
+
assert b53.decrypt(x1, salt) == bits
|
|
43
|
+
assert b53.decrypt(x2, salt) == bits
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Также доступны функции `encrypt_bool_array` / `decrypt_bool_array` и класс `B53Cipher` (`Cipher`):
|
|
47
|
+
|
|
48
|
+
```python
|
|
49
|
+
from b53 import B53Cipher
|
|
50
|
+
|
|
51
|
+
cipher = B53Cipher(salt)
|
|
52
|
+
encoded = cipher.encrypt_str("1011001011")
|
|
53
|
+
print(repr(encoded))
|
|
54
|
+
print(cipher.decrypt_str(encoded)) # "1011001011"
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
### CLI
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
# 1. Генерация соли
|
|
61
|
+
SALT=$(b53 generate-salt)
|
|
62
|
+
|
|
63
|
+
# 2. Три независимых шифрования одного массива
|
|
64
|
+
b53 encrypt 1011001011 --salt "$SALT" --count 3
|
|
65
|
+
|
|
66
|
+
# 3. Дешифрование
|
|
67
|
+
b53 decrypt 0.7419283058129402 --salt "$SALT"
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Поддерживаются запуск через `python -m b53 ...`, `--salt-file`, переменная окружения `B53_SALT` и флаг `-q` / `--quiet`.
|
|
71
|
+
|
|
72
|
+
## Математическая модель
|
|
73
|
+
|
|
74
|
+
Число на равномерной сетке $[0.0, 1.0)$ имеет вид $x = C \cdot 2^{-53}$, где $C \in \{0, 1, \dots, 2^{53} - 1\}$.
|
|
75
|
+
|
|
76
|
+
Всё пространство из $2^{53} = 9\,007\,199\,254\,740\,992$ состояний без остатка разбивается на 50 непересекающихся сегментов для $L \in [1, 50]$:
|
|
77
|
+
|
|
78
|
+
$$\sum_{L=1}^{50} M_L \cdot 2^L = 2^{53}$$
|
|
79
|
+
|
|
80
|
+
Бюджет распределяется адаптивно сверху вниз от $L = 50$ к $L = 1$ (около 25% остатка на шаг, не менее $M_L \ge 3$ вариантов на границе $L = 50$):
|
|
81
|
+
|
|
82
|
+
| Длина массива $L$ | Комбинаций ($2^L$) | Вариантов nonce ($M_L$) | Размер сегмента ($M_L \cdot 2^L$) |
|
|
83
|
+
|---:|---:|---:|---:|
|
|
84
|
+
| 50 | $2^{50}$ | 3 | $3 \times 2^{50}$ |
|
|
85
|
+
| 49 | $2^{49}$ | 3 | $3 \times 2^{49}$ |
|
|
86
|
+
| 48 | $2^{48}$ | 3 | $3 \times 2^{48}$ |
|
|
87
|
+
| 47 | $2^{47}$ | 5 | $5 \times 2^{47}$ |
|
|
88
|
+
| 45 | $2^{45}$ | 13 | $13 \times 2^{45}$ |
|
|
89
|
+
| 40 | $2^{40}$ | 100 | $100 \times 2^{40}$ |
|
|
90
|
+
| 30 | $2^{30}$ | 5 811 | $5\,811 \times 2^{30}$ |
|
|
91
|
+
| 20 | $2^{20}$ | 335 103 | $335\,103 \times 2^{20}$ |
|
|
92
|
+
| 10 | $2^{10}$ | 19 323 738 | $\approx 1{,}98 \times 10^{10}$ |
|
|
93
|
+
| 1 | $2^1$ | 2 971 477 630 | $\approx 5{,}94 \times 10^9$ |
|
|
94
|
+
|
|
95
|
+
## Требования к хранению и передаче `double`
|
|
96
|
+
|
|
97
|
+
При передаче через текст, CLI, CSV или JSON обязательно сохраняйте все 17 значащих цифр (`repr(x)` / `f"{x:.17g}"`, в PostgreSQL — бинарный тип `DOUBLE PRECISION` / `FLOAT8`). Округление даже последнего разряда разрушает младшие биты шифротекста.
|
|
98
|
+
|
|
99
|
+
## Разработка и тесты
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
pip install -e ".[dev]"
|
|
103
|
+
pytest
|
|
104
|
+
ruff check src tests
|
|
105
|
+
mypy src
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
## Лицензия
|
|
109
|
+
|
|
110
|
+
[MIT](LICENSE)
|
b53-0.1.0/pyproject.toml
ADDED
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling>=1.25"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "b53"
|
|
7
|
+
dynamic = ["version"]
|
|
8
|
+
description = "Reversible 53-bit cryptographic packing of 1-50 booleans with hidden length and random nonce into an IEEE 754 double in [0.0, 1.0)"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.10"
|
|
11
|
+
license = "MIT"
|
|
12
|
+
authors = [
|
|
13
|
+
{ name = "1orgar" },
|
|
14
|
+
]
|
|
15
|
+
keywords = [
|
|
16
|
+
"encryption",
|
|
17
|
+
"cipher",
|
|
18
|
+
"feistel",
|
|
19
|
+
"ieee754",
|
|
20
|
+
"double",
|
|
21
|
+
"boolean",
|
|
22
|
+
"bit-packing",
|
|
23
|
+
"format-preserving",
|
|
24
|
+
"hmac-sha256",
|
|
25
|
+
]
|
|
26
|
+
classifiers = [
|
|
27
|
+
"Development Status :: 4 - Beta",
|
|
28
|
+
"Intended Audience :: Developers",
|
|
29
|
+
"Intended Audience :: Science/Research",
|
|
30
|
+
"License :: OSI Approved :: MIT License",
|
|
31
|
+
"Operating System :: OS Independent",
|
|
32
|
+
"Programming Language :: Python :: 3",
|
|
33
|
+
"Programming Language :: Python :: 3.10",
|
|
34
|
+
"Programming Language :: Python :: 3.11",
|
|
35
|
+
"Programming Language :: Python :: 3.12",
|
|
36
|
+
"Programming Language :: Python :: 3.13",
|
|
37
|
+
"Programming Language :: Python :: 3.14",
|
|
38
|
+
"Topic :: Security :: Cryptography",
|
|
39
|
+
"Topic :: Software Development :: Libraries :: Python Modules",
|
|
40
|
+
"Typing :: Typed",
|
|
41
|
+
]
|
|
42
|
+
dependencies = []
|
|
43
|
+
|
|
44
|
+
[project.optional-dependencies]
|
|
45
|
+
dev = [
|
|
46
|
+
"build>=1.2",
|
|
47
|
+
"mypy>=1.11",
|
|
48
|
+
"pytest>=8.0",
|
|
49
|
+
"ruff>=0.8",
|
|
50
|
+
"twine>=6.1",
|
|
51
|
+
]
|
|
52
|
+
|
|
53
|
+
[project.scripts]
|
|
54
|
+
b53 = "b53.cli:main"
|
|
55
|
+
|
|
56
|
+
[project.urls]
|
|
57
|
+
Homepage = "https://github.com/1orgar/b53"
|
|
58
|
+
Repository = "https://github.com/1orgar/b53"
|
|
59
|
+
Issues = "https://github.com/1orgar/b53/issues"
|
|
60
|
+
|
|
61
|
+
[tool.hatch.version]
|
|
62
|
+
path = "src/b53/__init__.py"
|
|
63
|
+
|
|
64
|
+
[tool.hatch.build.targets.wheel]
|
|
65
|
+
packages = ["src/b53"]
|
|
66
|
+
|
|
67
|
+
[tool.hatch.build.targets.sdist]
|
|
68
|
+
include = [
|
|
69
|
+
"/src",
|
|
70
|
+
"/tests",
|
|
71
|
+
"/README.md",
|
|
72
|
+
"/README_RU.md",
|
|
73
|
+
"/LICENSE",
|
|
74
|
+
"/pyproject.toml",
|
|
75
|
+
]
|
|
76
|
+
|
|
77
|
+
[tool.pytest.ini_options]
|
|
78
|
+
testpaths = ["tests"]
|
|
79
|
+
addopts = "-ra"
|
|
80
|
+
|
|
81
|
+
[tool.ruff]
|
|
82
|
+
target-version = "py310"
|
|
83
|
+
line-length = 100
|
|
84
|
+
src = ["src", "tests"]
|
|
85
|
+
|
|
86
|
+
[tool.ruff.lint]
|
|
87
|
+
select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
|
|
88
|
+
|
|
89
|
+
[tool.mypy]
|
|
90
|
+
python_version = "3.10"
|
|
91
|
+
strict = true
|
|
92
|
+
packages = ["b53"]
|
|
93
|
+
mypy_path = "src"
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
"""b53 — Reversible 53-bit cryptographic packing of bool[1..50] into IEEE 754 double."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from b53.core import (
|
|
6
|
+
BASES,
|
|
7
|
+
DEFAULT_SALT_BYTES,
|
|
8
|
+
FEISTEL_ROUNDS,
|
|
9
|
+
LEFT_BITS,
|
|
10
|
+
MANTISSA_BITS,
|
|
11
|
+
MAX_LEN,
|
|
12
|
+
MIN_LEN,
|
|
13
|
+
MIN_SALT_BYTES,
|
|
14
|
+
NONCE_COUNTS,
|
|
15
|
+
RIGHT_BITS,
|
|
16
|
+
SIZES,
|
|
17
|
+
STATE_SPACE,
|
|
18
|
+
B53Cipher,
|
|
19
|
+
Cipher,
|
|
20
|
+
decrypt,
|
|
21
|
+
decrypt_bool_array,
|
|
22
|
+
encrypt,
|
|
23
|
+
encrypt_bool_array,
|
|
24
|
+
format_bits,
|
|
25
|
+
generate_salt,
|
|
26
|
+
parse_bits,
|
|
27
|
+
)
|
|
28
|
+
|
|
29
|
+
__version__ = "0.1.0"
|
|
30
|
+
|
|
31
|
+
__all__ = [
|
|
32
|
+
"BASES",
|
|
33
|
+
"DEFAULT_SALT_BYTES",
|
|
34
|
+
"FEISTEL_ROUNDS",
|
|
35
|
+
"LEFT_BITS",
|
|
36
|
+
"MANTISSA_BITS",
|
|
37
|
+
"MAX_LEN",
|
|
38
|
+
"MIN_LEN",
|
|
39
|
+
"MIN_SALT_BYTES",
|
|
40
|
+
"NONCE_COUNTS",
|
|
41
|
+
"RIGHT_BITS",
|
|
42
|
+
"SIZES",
|
|
43
|
+
"STATE_SPACE",
|
|
44
|
+
"B53Cipher",
|
|
45
|
+
"Cipher",
|
|
46
|
+
"__version__",
|
|
47
|
+
"decrypt",
|
|
48
|
+
"decrypt_bool_array",
|
|
49
|
+
"encrypt",
|
|
50
|
+
"encrypt_bool_array",
|
|
51
|
+
"format_bits",
|
|
52
|
+
"generate_salt",
|
|
53
|
+
"parse_bits",
|
|
54
|
+
]
|