kctsb 8.6.9__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.
- kctsb-8.6.9/MANIFEST.in +12 -0
- kctsb-8.6.9/PKG-INFO +235 -0
- kctsb-8.6.9/README.md +195 -0
- kctsb-8.6.9/kctsb/__init__.py +98 -0
- kctsb-8.6.9/kctsb/__init__.pyi +30 -0
- kctsb-8.6.9/kctsb/_kctsb_core.pyd +0 -0
- kctsb-8.6.9/kctsb/_libs/libgcc_s_seh-1.dll +0 -0
- kctsb-8.6.9/kctsb/_libs/libstdc++-6.dll +0 -0
- kctsb-8.6.9/kctsb/_libs/libwinpthread-1.dll +0 -0
- kctsb-8.6.9/kctsb/bfv.pyi +197 -0
- kctsb-8.6.9/kctsb/bgv.pyi +58 -0
- kctsb-8.6.9/kctsb/ckks.py +408 -0
- kctsb-8.6.9/kctsb/ckks.pyi +92 -0
- kctsb-8.6.9/kctsb/core.pyi +102 -0
- kctsb-8.6.9/kctsb/crypto.py +114 -0
- kctsb-8.6.9/kctsb/crypto.pyi +233 -0
- kctsb-8.6.9/kctsb/dp.py +316 -0
- kctsb-8.6.9/kctsb/dp.pyi +126 -0
- kctsb-8.6.9/kctsb/ecc_blind_sign.pyi +152 -0
- kctsb-8.6.9/kctsb/encode.pyi +62 -0
- kctsb-8.6.9/kctsb/hcc.pyi +89 -0
- kctsb-8.6.9/kctsb/ml/__init__.py +53 -0
- kctsb-8.6.9/kctsb/ml/encrypted_nn.py +353 -0
- kctsb-8.6.9/kctsb/ml/encrypted_ops.py +637 -0
- kctsb-8.6.9/kctsb/ml/encrypted_tensor.py +248 -0
- kctsb-8.6.9/kctsb/ml/he_ops.py +341 -0
- kctsb-8.6.9/kctsb/ml/pipeline.py +496 -0
- kctsb-8.6.9/kctsb/mpc.pyi +57 -0
- kctsb-8.6.9/kctsb/pir.pyi +117 -0
- kctsb-8.6.9/kctsb/psi.pyi +83 -0
- kctsb-8.6.9/kctsb/py.typed +0 -0
- kctsb-8.6.9/kctsb/sss.pyi +88 -0
- kctsb-8.6.9/kctsb/upsi.pyi +163 -0
- kctsb-8.6.9/kctsb/voprf.pyi +134 -0
- kctsb-8.6.9/kctsb.egg-info/PKG-INFO +235 -0
- kctsb-8.6.9/kctsb.egg-info/SOURCES.txt +40 -0
- kctsb-8.6.9/kctsb.egg-info/dependency_links.txt +1 -0
- kctsb-8.6.9/kctsb.egg-info/requires.txt +14 -0
- kctsb-8.6.9/kctsb.egg-info/top_level.txt +1 -0
- kctsb-8.6.9/pyproject.toml +66 -0
- kctsb-8.6.9/setup.cfg +4 -0
- kctsb-8.6.9/setup.py +23 -0
kctsb-8.6.9/MANIFEST.in
ADDED
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
include README.md
|
|
2
|
+
include LICENSE
|
|
3
|
+
|
|
4
|
+
recursive-include kctsb *.py *.pyd *.so *.dylib *.pyi
|
|
5
|
+
recursive-include kctsb/_libs *.dll *.so *.dylib
|
|
6
|
+
recursive-include kctsb/_kctsb_core *.pyi
|
|
7
|
+
include kctsb/py.typed
|
|
8
|
+
|
|
9
|
+
prune bindings
|
|
10
|
+
prune tests
|
|
11
|
+
prune __pycache__
|
|
12
|
+
global-exclude *.pyc
|
kctsb-8.6.9/PKG-INFO
ADDED
|
@@ -0,0 +1,235 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: kctsb
|
|
3
|
+
Version: 8.6.9
|
|
4
|
+
Summary: High-performance cryptographic library — HE (CKKS/BFV/BGV), DP, PSI/PIR, VOPRF, SSS, MPC, PQ encoding, and encrypted ML inference. C++ core with Python bindings.
|
|
5
|
+
Author-email: knightc <kcshareg@gmail.com>
|
|
6
|
+
License-Expression: Apache-2.0
|
|
7
|
+
Project-URL: Homepage, https://github.com/kn1ghtc/kctsb
|
|
8
|
+
Project-URL: Documentation, https://github.com/kn1ghtc/kctsb#readme
|
|
9
|
+
Project-URL: Repository, https://github.com/kn1ghtc/kctsb
|
|
10
|
+
Project-URL: Issues, https://github.com/kn1ghtc/kctsb/issues
|
|
11
|
+
Keywords: cryptography,homomorphic-encryption,ckks,bfv,bgv,differential-privacy,psi,pir,voprf,secret-sharing,mpc,garbled-circuit,rep3,secure-multiparty-computation,product-quantization,private-vector-search,encrypted-ml,privacy-preserving,pybind11
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Intended Audience :: Science/Research
|
|
15
|
+
Classifier: Operating System :: Microsoft :: Windows
|
|
16
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
17
|
+
Classifier: Operating System :: MacOS
|
|
18
|
+
Classifier: Programming Language :: Python :: 3
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
23
|
+
Classifier: Programming Language :: C++
|
|
24
|
+
Classifier: Topic :: Security :: Cryptography
|
|
25
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
26
|
+
Classifier: Topic :: Scientific/Engineering :: Mathematics
|
|
27
|
+
Requires-Python: >=3.10
|
|
28
|
+
Description-Content-Type: text/markdown
|
|
29
|
+
Requires-Dist: numpy>=1.24
|
|
30
|
+
Provides-Extra: ml
|
|
31
|
+
Requires-Dist: torch>=2.0; extra == "ml"
|
|
32
|
+
Requires-Dist: transformers>=4.30; extra == "ml"
|
|
33
|
+
Provides-Extra: dev
|
|
34
|
+
Requires-Dist: pytest>=7.0; extra == "dev"
|
|
35
|
+
Requires-Dist: pytest-cov; extra == "dev"
|
|
36
|
+
Requires-Dist: build; extra == "dev"
|
|
37
|
+
Requires-Dist: twine; extra == "dev"
|
|
38
|
+
Provides-Extra: all
|
|
39
|
+
Requires-Dist: kctsb[dev,ml]; extra == "all"
|
|
40
|
+
|
|
41
|
+
# kctsb — Knight's Cryptographic Trusted Security Base
|
|
42
|
+
|
|
43
|
+
High-performance cryptographic library with Python bindings for homomorphic encryption, differential privacy, private set intersection, PIR, MPC, Product Quantization (PQ) encoding, and encrypted ML inference.
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
**C++ core + pybind11 bindings → native Python speed**
|
|
47
|
+
|
|
48
|
+
## Features
|
|
49
|
+
|
|
50
|
+
| Module | Description |
|
|
51
|
+
|--------|-------------|
|
|
52
|
+
| `kctsb.crypto` | **v8.6.9** — atomic primitives: AES-GCM (AES-NI), ChaCha20-Poly1305, SHA-256/512/3 (SHA-NI), HMAC, HKDF, constant-time CSPRNG, `secure_compare`, `token_bytes`, `token_hex`; hand-written PEP 561 type stubs for all public symbols |
|
|
53
|
+
| `kctsb.ckks` | CKKS approximate homomorphic encryption (encode, encrypt, add, multiply, rotate) |
|
|
54
|
+
| `kctsb.bfv` | BFV scale-invariant FHE for integer arithmetic |
|
|
55
|
+
| `kctsb.bgv` | BGV leveled homomorphic encryption with Galois rotations |
|
|
56
|
+
| `kctsb.dp` | Differential privacy (Laplace, Gaussian mechanisms, budget tracking) |
|
|
57
|
+
| `kctsb.psi` | Private Set Intersection (Piano-PSI, OT-PSI with IKNP/KKRT) |
|
|
58
|
+
| `kctsb.pir` | Private Information Retrieval (FHE-based, BGV/BFV/CKKS) |
|
|
59
|
+
| `kctsb.ecc_blind_sign` | Clause Blind Schnorr signatures (FPS20) — ROS-resistant unlinkable tokens, public verifiable, AGM+ROM secure |
|
|
60
|
+
| `kctsb.voprf` | RFC 9497 VOPRF (P256-SHA256, OPRF/VOPRF/POPRF modes) — deterministic blinded PRF |
|
|
61
|
+
| `kctsb.sss` | Shamir's Secret Sharing (GF(2^8), information-theoretic security) |
|
|
62
|
+
| `kctsb.mpc` | Secure MPC primitives and benchmarks (Rep3 batch secret sharing, Half-Gates GC) |
|
|
63
|
+
| `kctsb.encode` | **v8.6.9** — Product Quantization training, encoding, decoding, ADC lookup, and ADC top-k for private vector query search (PVQS) |
|
|
64
|
+
| `kctsb.hcc` | Homomorphic Confidential Computing (6 privacy scenarios) |
|
|
65
|
+
| `kctsb.upsi` | Unbalanced PSI + Symmetric Searchable Encryption |
|
|
66
|
+
| `kctsb.core` | Hardware acceleration detection (AVX2/AVX512/AES-NI/CUDA) |
|
|
67
|
+
| `kctsb.ml` | Encrypted ML inference (EncryptedTensor, neural network layers, pipeline) |
|
|
68
|
+
|
|
69
|
+
## Quick Start
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
pip install kctsb
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
### Atomic Crypto Primitives (v8.6.9)
|
|
76
|
+
|
|
77
|
+
Hardware-accelerated primitives (AES-NI / SHA-NI). Requires Python 3.10+.
|
|
78
|
+
|
|
79
|
+
```python
|
|
80
|
+
from kctsb.crypto import (
|
|
81
|
+
AESGCM, ChaCha20Poly1305,
|
|
82
|
+
sha256, sha512, sha3_256,
|
|
83
|
+
hmac_sha256, hmac_sha512, hkdf_sha256,
|
|
84
|
+
random_bytes, random_uint32, random_uint64, random_range,
|
|
85
|
+
secure_compare, token_bytes, token_hex,
|
|
86
|
+
)
|
|
87
|
+
|
|
88
|
+
# AES-256-GCM (AES-NI accelerated)
|
|
89
|
+
key = AESGCM.generate_key(256) # bit length
|
|
90
|
+
nonce = random_bytes(12)
|
|
91
|
+
aead = AESGCM(key)
|
|
92
|
+
ct = aead.encrypt(nonce, b"hello", b"aad")
|
|
93
|
+
pt = aead.decrypt(nonce, ct, b"aad")
|
|
94
|
+
|
|
95
|
+
# SHA-NI accelerated hashing
|
|
96
|
+
digest = sha256(b"payload") # 32-byte bytes
|
|
97
|
+
tag = hmac_sha256(key, b"msg") # 32-byte bytes
|
|
98
|
+
|
|
99
|
+
# Constant-time CSPRNG (platform RtlGenRandom / getrandom)
|
|
100
|
+
secret = token_bytes(32)
|
|
101
|
+
hexstr = token_hex(16)
|
|
102
|
+
|
|
103
|
+
# HKDF-SHA256
|
|
104
|
+
okm = hkdf_sha256(ikm=secret, salt=b"salt", info=b"context", length=64)
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
### Product Quantization Encoding (v8.6.9)
|
|
108
|
+
|
|
109
|
+
Compress high-dimensional feature vectors into compact PQ codes and run ADC top-k search. This module is designed for PVQS-style private vector retrieval pipelines where the online private query only carries compact candidate/key handles.
|
|
110
|
+
|
|
111
|
+
```python
|
|
112
|
+
import numpy as np
|
|
113
|
+
from kctsb import encode
|
|
114
|
+
|
|
115
|
+
vectors = np.random.default_rng(20260508).normal(size=(4096, 512)).astype(np.float32)
|
|
116
|
+
query = vectors[0]
|
|
117
|
+
|
|
118
|
+
codebooks = encode.train_pq(vectors, subquantizers=32, centroids=64, max_iterations=8)
|
|
119
|
+
codes = encode.encode_pq(vectors, codebooks)
|
|
120
|
+
lookup = encode.adc_lookup(query, codebooks)
|
|
121
|
+
indices, distances = encode.adc_topk(codes, lookup, top_k=10)
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
### CKKS Homomorphic Encryption
|
|
125
|
+
|
|
126
|
+
```python
|
|
127
|
+
from kctsb import CKKSContext
|
|
128
|
+
|
|
129
|
+
ctx = CKKSContext(poly_modulus_degree=8192, coeff_modulus_levels=5, scale_bits=40)
|
|
130
|
+
sk = ctx.keygen()
|
|
131
|
+
pk = ctx.public_key(sk)
|
|
132
|
+
|
|
133
|
+
pt = ctx.encode([1.0, 2.0, 3.0])
|
|
134
|
+
ct = ctx.encrypt(pk, pt)
|
|
135
|
+
ct_sum = ctx.add(ct, ct)
|
|
136
|
+
result = ctx.decrypt_decode(sk, ct_sum)
|
|
137
|
+
print(result[:3]) # [2.0, 4.0, 6.0]
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
### Differential Privacy
|
|
141
|
+
|
|
142
|
+
```python
|
|
143
|
+
from kctsb.dp import DPMechanism, DPBudget
|
|
144
|
+
|
|
145
|
+
noise = DPMechanism.laplace(sensitivity=1.0, epsilon=0.1)
|
|
146
|
+
noisy_data = DPMechanism.add_noise([1.0, 2.0, 3.0], sensitivity=1.0, epsilon=0.1)
|
|
147
|
+
|
|
148
|
+
budget = DPBudget(total_epsilon=1.0)
|
|
149
|
+
budget.consume(0.1)
|
|
150
|
+
print(f"Remaining ε: {budget.remaining_epsilon}")
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
### Private Set Intersection
|
|
154
|
+
|
|
155
|
+
```python
|
|
156
|
+
from kctsb._kctsb_core import psi
|
|
157
|
+
|
|
158
|
+
client_set = list(range(1, 101))
|
|
159
|
+
server_set = list(range(50, 151))
|
|
160
|
+
piano = psi.PianoPSI()
|
|
161
|
+
result = piano.compute(client_set, server_set)
|
|
162
|
+
print(f"Intersection size: {len(result.intersection)}")
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
### Multi-Party Computation (MPC)
|
|
166
|
+
|
|
167
|
+
The Python package now exposes `kctsb.mpc` for secure MPC primitives and performance benchmarking. Use this module to access Rep3 batch secret sharing APIs and Half-Gates garbled-circuit benchmarks directly from Python.
|
|
168
|
+
|
|
169
|
+
### Shamir's Secret Sharing
|
|
170
|
+
|
|
171
|
+
```python
|
|
172
|
+
from kctsb._kctsb_core import sss
|
|
173
|
+
|
|
174
|
+
secret = b"my_secret_key_32bytes_long!!!!!"
|
|
175
|
+
shares = sss.ShamirSSS.split(secret, threshold=3, num_shares=5)
|
|
176
|
+
recovered = sss.ShamirSSS.reconstruct(shares[:3], len(secret))
|
|
177
|
+
assert recovered == secret
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
### Hardware Detection
|
|
181
|
+
|
|
182
|
+
```python
|
|
183
|
+
from kctsb._kctsb_core import core
|
|
184
|
+
|
|
185
|
+
hw = core.detect_hardware()
|
|
186
|
+
print(f"AVX2: {hw['avx2']}, AES-NI: {hw['aes_ni']}, CUDA: {hw['cuda']}")
|
|
187
|
+
core.print_status()
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
## Building from Source
|
|
191
|
+
|
|
192
|
+
Developers with the full kctsb source tree can build locally:
|
|
193
|
+
|
|
194
|
+
```powershell
|
|
195
|
+
# Windows (PowerShell)
|
|
196
|
+
cd kctsb
|
|
197
|
+
.\scripts\build_python.ps1
|
|
198
|
+
|
|
199
|
+
# Or manually:
|
|
200
|
+
$env:PATH = "C:\msys64\mingw64\bin;$env:PATH"
|
|
201
|
+
cmake -B build_release -G Ninja -DCMAKE_BUILD_TYPE=Release -DKCTSB_BUILD_PYTHON=ON
|
|
202
|
+
cmake --build build_release --parallel 16
|
|
203
|
+
pip install ./python
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
## Requirements
|
|
207
|
+
|
|
208
|
+
- Python 3.10+
|
|
209
|
+
- NumPy >= 1.24
|
|
210
|
+
- Windows x64 (pre-built), Linux/macOS (build from source)
|
|
211
|
+
|
|
212
|
+
## Optional Dependencies
|
|
213
|
+
|
|
214
|
+
```bash
|
|
215
|
+
pip install kctsb[ml] # + torch, transformers for encrypted ML
|
|
216
|
+
pip install kctsb[dev] # + pytest, build, twine for development
|
|
217
|
+
pip install kctsb[all] # Everything
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
## Changelog
|
|
221
|
+
|
|
222
|
+
### v8.6.9 (2026-05)
|
|
223
|
+
- Added `kctsb.encode` Product Quantization primitives for PVQS: PQ training, batch encode/decode, ADC lookup, and ADC top-k.
|
|
224
|
+
- Added PEP 561 type hints for `kctsb.encode` and refreshed blind-signature stubs to match the P-256 pybind11 API.
|
|
225
|
+
- Added PVQS notebook and protocol design documentation for low-communication private theme/resource retrieval.
|
|
226
|
+
|
|
227
|
+
### v8.6.6 (2026-04)
|
|
228
|
+
- **Breaking**: removed `_hashlib` / `_hmac` compat shim objects from `kctsb.crypto`.
|
|
229
|
+
Use `sha256`, `hmac_sha256`, `token_bytes` etc. directly.
|
|
230
|
+
- Added hand-written PEP 561 type stubs (`*.pyi`) for all public symbols in
|
|
231
|
+
`kctsb.crypto`, `kctsb.ckks`, `kctsb.dp`, `kctsb.sss` and all `_kctsb_core` sub-modules.
|
|
232
|
+
- Secure RAG demo: Phase 0 bootstrap and corpus loader extracted to standalone helper modules.
|
|
233
|
+
|
|
234
|
+
## License
|
|
235
|
+
Apache-2.0 — Copyright (c) 2019-2026 knightc
|
kctsb-8.6.9/README.md
ADDED
|
@@ -0,0 +1,195 @@
|
|
|
1
|
+
# kctsb — Knight's Cryptographic Trusted Security Base
|
|
2
|
+
|
|
3
|
+
High-performance cryptographic library with Python bindings for homomorphic encryption, differential privacy, private set intersection, PIR, MPC, Product Quantization (PQ) encoding, and encrypted ML inference.
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
**C++ core + pybind11 bindings → native Python speed**
|
|
7
|
+
|
|
8
|
+
## Features
|
|
9
|
+
|
|
10
|
+
| Module | Description |
|
|
11
|
+
|--------|-------------|
|
|
12
|
+
| `kctsb.crypto` | **v8.6.9** — atomic primitives: AES-GCM (AES-NI), ChaCha20-Poly1305, SHA-256/512/3 (SHA-NI), HMAC, HKDF, constant-time CSPRNG, `secure_compare`, `token_bytes`, `token_hex`; hand-written PEP 561 type stubs for all public symbols |
|
|
13
|
+
| `kctsb.ckks` | CKKS approximate homomorphic encryption (encode, encrypt, add, multiply, rotate) |
|
|
14
|
+
| `kctsb.bfv` | BFV scale-invariant FHE for integer arithmetic |
|
|
15
|
+
| `kctsb.bgv` | BGV leveled homomorphic encryption with Galois rotations |
|
|
16
|
+
| `kctsb.dp` | Differential privacy (Laplace, Gaussian mechanisms, budget tracking) |
|
|
17
|
+
| `kctsb.psi` | Private Set Intersection (Piano-PSI, OT-PSI with IKNP/KKRT) |
|
|
18
|
+
| `kctsb.pir` | Private Information Retrieval (FHE-based, BGV/BFV/CKKS) |
|
|
19
|
+
| `kctsb.ecc_blind_sign` | Clause Blind Schnorr signatures (FPS20) — ROS-resistant unlinkable tokens, public verifiable, AGM+ROM secure |
|
|
20
|
+
| `kctsb.voprf` | RFC 9497 VOPRF (P256-SHA256, OPRF/VOPRF/POPRF modes) — deterministic blinded PRF |
|
|
21
|
+
| `kctsb.sss` | Shamir's Secret Sharing (GF(2^8), information-theoretic security) |
|
|
22
|
+
| `kctsb.mpc` | Secure MPC primitives and benchmarks (Rep3 batch secret sharing, Half-Gates GC) |
|
|
23
|
+
| `kctsb.encode` | **v8.6.9** — Product Quantization training, encoding, decoding, ADC lookup, and ADC top-k for private vector query search (PVQS) |
|
|
24
|
+
| `kctsb.hcc` | Homomorphic Confidential Computing (6 privacy scenarios) |
|
|
25
|
+
| `kctsb.upsi` | Unbalanced PSI + Symmetric Searchable Encryption |
|
|
26
|
+
| `kctsb.core` | Hardware acceleration detection (AVX2/AVX512/AES-NI/CUDA) |
|
|
27
|
+
| `kctsb.ml` | Encrypted ML inference (EncryptedTensor, neural network layers, pipeline) |
|
|
28
|
+
|
|
29
|
+
## Quick Start
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
pip install kctsb
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
### Atomic Crypto Primitives (v8.6.9)
|
|
36
|
+
|
|
37
|
+
Hardware-accelerated primitives (AES-NI / SHA-NI). Requires Python 3.10+.
|
|
38
|
+
|
|
39
|
+
```python
|
|
40
|
+
from kctsb.crypto import (
|
|
41
|
+
AESGCM, ChaCha20Poly1305,
|
|
42
|
+
sha256, sha512, sha3_256,
|
|
43
|
+
hmac_sha256, hmac_sha512, hkdf_sha256,
|
|
44
|
+
random_bytes, random_uint32, random_uint64, random_range,
|
|
45
|
+
secure_compare, token_bytes, token_hex,
|
|
46
|
+
)
|
|
47
|
+
|
|
48
|
+
# AES-256-GCM (AES-NI accelerated)
|
|
49
|
+
key = AESGCM.generate_key(256) # bit length
|
|
50
|
+
nonce = random_bytes(12)
|
|
51
|
+
aead = AESGCM(key)
|
|
52
|
+
ct = aead.encrypt(nonce, b"hello", b"aad")
|
|
53
|
+
pt = aead.decrypt(nonce, ct, b"aad")
|
|
54
|
+
|
|
55
|
+
# SHA-NI accelerated hashing
|
|
56
|
+
digest = sha256(b"payload") # 32-byte bytes
|
|
57
|
+
tag = hmac_sha256(key, b"msg") # 32-byte bytes
|
|
58
|
+
|
|
59
|
+
# Constant-time CSPRNG (platform RtlGenRandom / getrandom)
|
|
60
|
+
secret = token_bytes(32)
|
|
61
|
+
hexstr = token_hex(16)
|
|
62
|
+
|
|
63
|
+
# HKDF-SHA256
|
|
64
|
+
okm = hkdf_sha256(ikm=secret, salt=b"salt", info=b"context", length=64)
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
### Product Quantization Encoding (v8.6.9)
|
|
68
|
+
|
|
69
|
+
Compress high-dimensional feature vectors into compact PQ codes and run ADC top-k search. This module is designed for PVQS-style private vector retrieval pipelines where the online private query only carries compact candidate/key handles.
|
|
70
|
+
|
|
71
|
+
```python
|
|
72
|
+
import numpy as np
|
|
73
|
+
from kctsb import encode
|
|
74
|
+
|
|
75
|
+
vectors = np.random.default_rng(20260508).normal(size=(4096, 512)).astype(np.float32)
|
|
76
|
+
query = vectors[0]
|
|
77
|
+
|
|
78
|
+
codebooks = encode.train_pq(vectors, subquantizers=32, centroids=64, max_iterations=8)
|
|
79
|
+
codes = encode.encode_pq(vectors, codebooks)
|
|
80
|
+
lookup = encode.adc_lookup(query, codebooks)
|
|
81
|
+
indices, distances = encode.adc_topk(codes, lookup, top_k=10)
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
### CKKS Homomorphic Encryption
|
|
85
|
+
|
|
86
|
+
```python
|
|
87
|
+
from kctsb import CKKSContext
|
|
88
|
+
|
|
89
|
+
ctx = CKKSContext(poly_modulus_degree=8192, coeff_modulus_levels=5, scale_bits=40)
|
|
90
|
+
sk = ctx.keygen()
|
|
91
|
+
pk = ctx.public_key(sk)
|
|
92
|
+
|
|
93
|
+
pt = ctx.encode([1.0, 2.0, 3.0])
|
|
94
|
+
ct = ctx.encrypt(pk, pt)
|
|
95
|
+
ct_sum = ctx.add(ct, ct)
|
|
96
|
+
result = ctx.decrypt_decode(sk, ct_sum)
|
|
97
|
+
print(result[:3]) # [2.0, 4.0, 6.0]
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
### Differential Privacy
|
|
101
|
+
|
|
102
|
+
```python
|
|
103
|
+
from kctsb.dp import DPMechanism, DPBudget
|
|
104
|
+
|
|
105
|
+
noise = DPMechanism.laplace(sensitivity=1.0, epsilon=0.1)
|
|
106
|
+
noisy_data = DPMechanism.add_noise([1.0, 2.0, 3.0], sensitivity=1.0, epsilon=0.1)
|
|
107
|
+
|
|
108
|
+
budget = DPBudget(total_epsilon=1.0)
|
|
109
|
+
budget.consume(0.1)
|
|
110
|
+
print(f"Remaining ε: {budget.remaining_epsilon}")
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
### Private Set Intersection
|
|
114
|
+
|
|
115
|
+
```python
|
|
116
|
+
from kctsb._kctsb_core import psi
|
|
117
|
+
|
|
118
|
+
client_set = list(range(1, 101))
|
|
119
|
+
server_set = list(range(50, 151))
|
|
120
|
+
piano = psi.PianoPSI()
|
|
121
|
+
result = piano.compute(client_set, server_set)
|
|
122
|
+
print(f"Intersection size: {len(result.intersection)}")
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
### Multi-Party Computation (MPC)
|
|
126
|
+
|
|
127
|
+
The Python package now exposes `kctsb.mpc` for secure MPC primitives and performance benchmarking. Use this module to access Rep3 batch secret sharing APIs and Half-Gates garbled-circuit benchmarks directly from Python.
|
|
128
|
+
|
|
129
|
+
### Shamir's Secret Sharing
|
|
130
|
+
|
|
131
|
+
```python
|
|
132
|
+
from kctsb._kctsb_core import sss
|
|
133
|
+
|
|
134
|
+
secret = b"my_secret_key_32bytes_long!!!!!"
|
|
135
|
+
shares = sss.ShamirSSS.split(secret, threshold=3, num_shares=5)
|
|
136
|
+
recovered = sss.ShamirSSS.reconstruct(shares[:3], len(secret))
|
|
137
|
+
assert recovered == secret
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
### Hardware Detection
|
|
141
|
+
|
|
142
|
+
```python
|
|
143
|
+
from kctsb._kctsb_core import core
|
|
144
|
+
|
|
145
|
+
hw = core.detect_hardware()
|
|
146
|
+
print(f"AVX2: {hw['avx2']}, AES-NI: {hw['aes_ni']}, CUDA: {hw['cuda']}")
|
|
147
|
+
core.print_status()
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
## Building from Source
|
|
151
|
+
|
|
152
|
+
Developers with the full kctsb source tree can build locally:
|
|
153
|
+
|
|
154
|
+
```powershell
|
|
155
|
+
# Windows (PowerShell)
|
|
156
|
+
cd kctsb
|
|
157
|
+
.\scripts\build_python.ps1
|
|
158
|
+
|
|
159
|
+
# Or manually:
|
|
160
|
+
$env:PATH = "C:\msys64\mingw64\bin;$env:PATH"
|
|
161
|
+
cmake -B build_release -G Ninja -DCMAKE_BUILD_TYPE=Release -DKCTSB_BUILD_PYTHON=ON
|
|
162
|
+
cmake --build build_release --parallel 16
|
|
163
|
+
pip install ./python
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
## Requirements
|
|
167
|
+
|
|
168
|
+
- Python 3.10+
|
|
169
|
+
- NumPy >= 1.24
|
|
170
|
+
- Windows x64 (pre-built), Linux/macOS (build from source)
|
|
171
|
+
|
|
172
|
+
## Optional Dependencies
|
|
173
|
+
|
|
174
|
+
```bash
|
|
175
|
+
pip install kctsb[ml] # + torch, transformers for encrypted ML
|
|
176
|
+
pip install kctsb[dev] # + pytest, build, twine for development
|
|
177
|
+
pip install kctsb[all] # Everything
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
## Changelog
|
|
181
|
+
|
|
182
|
+
### v8.6.9 (2026-05)
|
|
183
|
+
- Added `kctsb.encode` Product Quantization primitives for PVQS: PQ training, batch encode/decode, ADC lookup, and ADC top-k.
|
|
184
|
+
- Added PEP 561 type hints for `kctsb.encode` and refreshed blind-signature stubs to match the P-256 pybind11 API.
|
|
185
|
+
- Added PVQS notebook and protocol design documentation for low-communication private theme/resource retrieval.
|
|
186
|
+
|
|
187
|
+
### v8.6.6 (2026-04)
|
|
188
|
+
- **Breaking**: removed `_hashlib` / `_hmac` compat shim objects from `kctsb.crypto`.
|
|
189
|
+
Use `sha256`, `hmac_sha256`, `token_bytes` etc. directly.
|
|
190
|
+
- Added hand-written PEP 561 type stubs (`*.pyi`) for all public symbols in
|
|
191
|
+
`kctsb.crypto`, `kctsb.ckks`, `kctsb.dp`, `kctsb.sss` and all `_kctsb_core` sub-modules.
|
|
192
|
+
- Secure RAG demo: Phase 0 bootstrap and corpus loader extracted to standalone helper modules.
|
|
193
|
+
|
|
194
|
+
## License
|
|
195
|
+
Apache-2.0 — Copyright (c) 2019-2026 knightc
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
"""
|
|
2
|
+
kctsb - Knight's Cryptographic Trusted Security Base (Python Interface)
|
|
3
|
+
|
|
4
|
+
High-performance homomorphic encryption, differential privacy, and encrypted
|
|
5
|
+
ML inference library. Python bindings for the kctsb C++ cryptographic core.
|
|
6
|
+
|
|
7
|
+
Architecture:
|
|
8
|
+
Python API (kctsb.ckks, kctsb.dp, kctsb.ml)
|
|
9
|
+
↓
|
|
10
|
+
pybind11 bindings (_kctsb_core)
|
|
11
|
+
↓
|
|
12
|
+
C++ core (libkctsb_static)
|
|
13
|
+
|
|
14
|
+
Usage:
|
|
15
|
+
>>> import kctsb
|
|
16
|
+
>>> ctx = kctsb.CKKSContext(poly_modulus_degree=8192,
|
|
17
|
+
... coeff_modulus_levels=5,
|
|
18
|
+
... scale_bits=40)
|
|
19
|
+
>>> sk = ctx.keygen()
|
|
20
|
+
>>> pk = ctx.public_key(sk)
|
|
21
|
+
>>> pt = ctx.encode([1.0, 2.0, 3.0])
|
|
22
|
+
>>> ct = ctx.encrypt(pk, pt)
|
|
23
|
+
>>> result = ctx.decrypt(sk, ct)
|
|
24
|
+
>>> values = ctx.decode(result)
|
|
25
|
+
|
|
26
|
+
Author: knightc
|
|
27
|
+
Copyright: (c) 2019-2026 knightc. All rights reserved.
|
|
28
|
+
License: Apache-2.0
|
|
29
|
+
"""
|
|
30
|
+
|
|
31
|
+
import os
|
|
32
|
+
import sys
|
|
33
|
+
import logging
|
|
34
|
+
|
|
35
|
+
__version__ = "8.6.9"
|
|
36
|
+
__author__ = "knightc"
|
|
37
|
+
|
|
38
|
+
logger = logging.getLogger(__name__)
|
|
39
|
+
|
|
40
|
+
# ---------------------------------------------------------------------------
|
|
41
|
+
# DLL loader: add bundled runtime libraries to DLL search path (Windows)
|
|
42
|
+
# ---------------------------------------------------------------------------
|
|
43
|
+
_libs_dir = os.path.join(os.path.dirname(__file__), "_libs")
|
|
44
|
+
_dll_handle = None
|
|
45
|
+
if sys.platform == "win32" and os.path.isdir(_libs_dir):
|
|
46
|
+
try:
|
|
47
|
+
_dll_handle = os.add_dll_directory(_libs_dir)
|
|
48
|
+
logger.debug("Added DLL directory: %s", _libs_dir)
|
|
49
|
+
except OSError:
|
|
50
|
+
logger.warning("Failed to add DLL directory: %s", _libs_dir)
|
|
51
|
+
|
|
52
|
+
# Try to import the compiled C++ core module
|
|
53
|
+
try:
|
|
54
|
+
from ._kctsb_core import ckks as _ckks_core
|
|
55
|
+
from ._kctsb_core import dp as _dp_core
|
|
56
|
+
from ._kctsb_core import __version__ as _core_version
|
|
57
|
+
_HAS_CORE = True
|
|
58
|
+
except ImportError as exc:
|
|
59
|
+
_HAS_CORE = False
|
|
60
|
+
_core_version = "N/A (core not compiled)"
|
|
61
|
+
logger.warning("kctsb C++ core not available: %s", exc)
|
|
62
|
+
|
|
63
|
+
# Re-export C++ submodules without Python wrapper conflicts
|
|
64
|
+
# Usage: from kctsb import bfv, psi, pir, crypto, ...
|
|
65
|
+
if _HAS_CORE:
|
|
66
|
+
from ._kctsb_core import bfv, bgv, psi, pir, hcc, upsi, voprf, sss, core, mpc
|
|
67
|
+
from ._kctsb_core import ecc_blind_sign
|
|
68
|
+
from ._kctsb_core import encode
|
|
69
|
+
|
|
70
|
+
# High-level Python facades (keep these AFTER the core re-exports so they win on name conflicts)
|
|
71
|
+
from . import crypto
|
|
72
|
+
from .ckks import CKKSContext
|
|
73
|
+
from .dp import DPMechanism, DPBudget
|
|
74
|
+
from . import dp
|
|
75
|
+
|
|
76
|
+
__all__ = [
|
|
77
|
+
# High-level Python wrappers
|
|
78
|
+
"CKKSContext",
|
|
79
|
+
"DPMechanism",
|
|
80
|
+
"DPBudget",
|
|
81
|
+
# Python facade modules
|
|
82
|
+
"crypto",
|
|
83
|
+
"dp",
|
|
84
|
+
# C++ submodules (direct re-exports)
|
|
85
|
+
"bfv",
|
|
86
|
+
"bgv",
|
|
87
|
+
"psi",
|
|
88
|
+
"pir",
|
|
89
|
+
"hcc",
|
|
90
|
+
"upsi",
|
|
91
|
+
"voprf",
|
|
92
|
+
"ecc_blind_sign",
|
|
93
|
+
"sss",
|
|
94
|
+
"core",
|
|
95
|
+
"mpc",
|
|
96
|
+
"encode",
|
|
97
|
+
"__version__",
|
|
98
|
+
]
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
"""Type stubs for the top-level ``kctsb`` package.
|
|
2
|
+
|
|
3
|
+
Re-exports the high-level Python facades (:class:`CKKSContext`,
|
|
4
|
+
:class:`DPMechanism`, :class:`DPBudget`) and the C++ submodules
|
|
5
|
+
(``crypto``, ``dp``, ``ckks``, ``bfv``, ``bgv``, ``psi``, ``pir``,
|
|
6
|
+
``hcc``, ``upsi``, ``voprf``, ``sss``, ``core``, ``mpc``).
|
|
7
|
+
"""
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
from . import bfv as bfv
|
|
11
|
+
from . import bgv as bgv
|
|
12
|
+
from . import ckks as ckks
|
|
13
|
+
from . import core as core
|
|
14
|
+
from . import crypto as crypto
|
|
15
|
+
from . import dp as dp
|
|
16
|
+
from . import ecc_blind_sign as ecc_blind_sign
|
|
17
|
+
from . import hcc as hcc
|
|
18
|
+
from . import mpc as mpc
|
|
19
|
+
from . import pir as pir
|
|
20
|
+
from . import psi as psi
|
|
21
|
+
from . import sss as sss
|
|
22
|
+
from . import upsi as upsi
|
|
23
|
+
from . import voprf as voprf
|
|
24
|
+
from .ckks import CKKSContext as CKKSContext
|
|
25
|
+
from .dp import DPBudget as DPBudget, DPMechanism as DPMechanism
|
|
26
|
+
|
|
27
|
+
__version__: str
|
|
28
|
+
__author__: str
|
|
29
|
+
|
|
30
|
+
__all__: list[str]
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|