Metadata-Version: 2.4
Name: kctsb
Version: 9.5.0
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.
Author-email: knightc <kcshareg@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/kn1ghtc/kctsb
Project-URL: Documentation, https://github.com/kn1ghtc/kctsb#readme
Project-URL: Repository, https://github.com/kn1ghtc/kctsb
Project-URL: Issues, https://github.com/kn1ghtc/kctsb/issues
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
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: C++
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Provides-Extra: ml
Requires-Dist: torch>=2.0; extra == "ml"
Requires-Dist: transformers>=4.30; extra == "ml"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Provides-Extra: all
Requires-Dist: kctsb[dev,ml]; extra == "all"
Dynamic: license-file

# kctsb — Knight's Cryptographic Trusted Security Base

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.


**C++ core + pybind11 bindings → native Python speed**

## Features

| Module | Description |
|--------|-------------|
| `kctsb` | **v9.5.0 current tree** — production crypto is OpenSSL-clean and self-contained: SHA-512 / HMAC-SHA512 uses the kctsb C++ WK3 register-ahead compression path only, while OpenSSL remains benchmark/reference-only under `benchmarks/`. OpenSSL 3.6.0 head-to-head best-of-4 reports SHA-512 1MB/10MB and HMAC-SHA512 1MB/10MB as `1.03x/1.09x/1.06x/1.07x` GOOD-or-better, and RSA-3072 PSS Sign/OAEP Decrypt as `0.85x/0.84x` GOOD-or-better. v9.3.1 ChaCha20-Poly1305 one-shot AEAD remains tracked as GOOD-or-better, BFV HPSOverQ defaults from v9.2.2 remain active for verified `n=8192..32768,L≥3,size-2`, and no modulus, plaintext modulus, secret distribution, noise-sampling security parameters, tag semantics, or secret-path constant-time policies are weakened. |
| `kctsb.crypto` | 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 |
| `kctsb.ckks` | CKKS approximate homomorphic encryption (encode, encrypt, add, multiply, rotate) |
| `kctsb.bfv` | BFV scale-invariant FHE for integer arithmetic |
| `kctsb.bgv` | BGV leveled homomorphic encryption with Galois rotations |
| `kctsb.dp` | Differential privacy (Laplace, Gaussian mechanisms, budget tracking) |
| `kctsb.psi` | Private Set Intersection with domain-separated SHA-256 tokens, constant-time token equality, CSPRNG sampling, and PIR provider-unavailable paths that fail closed with security-policy errors instead of plaintext fallback |
| `kctsb.pir` | Private Information Retrieval (FHE-based, BGV/BFV/CKKS) |
| `kctsb.ecc_blind_sign` | Clause Blind Schnorr signatures (FPS20) — ROS-resistant unlinkable tokens, public verifiable, AGM+ROM secure |
| `kctsb.voprf` | RFC 9497 VOPRF (P256-SHA256, OPRF/VOPRF/POPRF modes) — deterministic blinded PRF |
| `kctsb.sss` | Shamir's Secret Sharing (GF(2^8), information-theoretic security) |
| `kctsb.mpc` | Secure MPC primitives and benchmarks (Rep3 batch secret sharing, Half-Gates GC) |
| `kctsb.encode` | Product Quantization training, encoding, decoding, ADC lookup, and ADC top-k for private vector query search (PVQS) |
| `kctsb.hcc` | Homomorphic Confidential Computing (6 privacy scenarios) |
| `kctsb.upsi` | Unbalanced PSI + Symmetric Searchable Encryption |
| `kctsb.core` | Hardware acceleration detection (AVX2/AVX512/AES-NI/CUDA) |
| `kctsb.ml` | Encrypted ML inference (EncryptedTensor, neural network layers, pipeline) |

## Quick Start

```bash
pip install kctsb
```

### Atomic Crypto Primitives

Hardware-accelerated primitives (AES-NI / SHA-NI). Requires Python 3.10+.

```python
from kctsb.crypto import (
    AESGCM, ChaCha20Poly1305,
    sha256, sha512, sha3_256,
    hmac_sha256, hmac_sha512, hkdf_sha256,
    random_bytes, random_uint32, random_uint64, random_range,
    secure_compare, token_bytes, token_hex,
)

# AES-256-GCM (AES-NI accelerated)
key = AESGCM.generate_key(256)     # bit length
nonce = random_bytes(12)
aead = AESGCM(key)
ct = aead.encrypt(nonce, b"hello", b"aad")
pt = aead.decrypt(nonce, ct, b"aad")

# SHA-NI accelerated hashing
digest = sha256(b"payload")         # 32-byte bytes
tag    = hmac_sha256(key, b"msg")   # 32-byte bytes

# Constant-time CSPRNG (platform RtlGenRandom / getrandom)
secret = token_bytes(32)
hexstr = token_hex(16)

# HKDF-SHA256
okm = hkdf_sha256(ikm=secret, salt=b"salt", info=b"context", length=64)
```

### Product Quantization Encoding

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.

```python
import numpy as np
from kctsb import encode

vectors = np.random.default_rng(20260508).normal(size=(4096, 512)).astype(np.float32)
query = vectors[0]

codebooks = encode.train_pq(vectors, subquantizers=32, centroids=64, max_iterations=8)
codes = encode.encode_pq(vectors, codebooks)
lookup = encode.adc_lookup(query, codebooks)
indices, distances = encode.adc_topk(codes, lookup, top_k=10)
```

### CKKS Homomorphic Encryption

```python
from kctsb import CKKSContext

ctx = CKKSContext(poly_modulus_degree=8192, coeff_modulus_levels=5, scale_bits=40)
sk = ctx.keygen()
pk = ctx.public_key(sk)

pt = ctx.encode([1.0, 2.0, 3.0])
ct = ctx.encrypt(pk, pt)
ct_sum = ctx.add(ct, ct)
result = ctx.decrypt_decode(sk, ct_sum)
print(result[:3])  # [2.0, 4.0, 6.0]
```

### Differential Privacy

```python
from kctsb.dp import DPMechanism, DPBudget

noise = DPMechanism.laplace(sensitivity=1.0, epsilon=0.1)
noisy_data = DPMechanism.add_noise([1.0, 2.0, 3.0], sensitivity=1.0, epsilon=0.1)

budget = DPBudget(total_epsilon=1.0)
budget.consume(0.1)
print(f"Remaining ε: {budget.remaining_epsilon}")
```

### Private Set Intersection

```python
from kctsb._kctsb_core import psi

client_set = list(range(1, 101))
server_set = list(range(50, 151))
piano = psi.PianoPSI()
result = piano.compute(client_set, server_set)
print(f"Intersection size: {len(result.intersection)}")
```

### Multi-Party Computation (MPC)

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.

### Shamir's Secret Sharing

```python
from kctsb._kctsb_core import sss

secret = b"my_secret_key_32bytes_long!!!!!"
shares = sss.ShamirSSS.split(secret, threshold=3, num_shares=5)
recovered = sss.ShamirSSS.reconstruct(shares[:3], len(secret))
assert recovered == secret
```

### Hardware Detection

```python
from kctsb._kctsb_core import core

hw = core.detect_hardware()
print(f"AVX2: {hw['avx2']}, AES-NI: {hw['aes_ni']}, CUDA: {hw['cuda']}")
core.print_status()
```

## Building from Source

Developers with the full kctsb source tree can build locally:

```powershell
# Windows (PowerShell)
cd kctsb
.\scripts\build_python.ps1

# Or manually:
$env:PATH = "C:\msys64\mingw64\bin;$env:PATH"
cmake -B build_release -G Ninja -DCMAKE_BUILD_TYPE=Release -DKCTSB_BUILD_PYTHON=ON
cmake --build build_release --parallel 16
pip install ./python
```

## Requirements

- Python 3.10+
- NumPy >= 1.24
- Windows x64 (pre-built), Linux/macOS (build from source)

## Optional Dependencies

```bash
pip install kctsb[ml]   # + torch, transformers for encrypted ML
pip install kctsb[dev]  # + pytest, build, twine for development
pip install kctsb[all]  # Everything
```

## Changelog

### v9.5.0 (2026-05)
- Restored the production SHA-512 / HMAC-SHA512 path to self-contained kctsb C++ only; OpenSSL is benchmark/reference-only and is not linked, generated into, or dynamically imported by the shipped library.
- Added constant-time RSA-3072 CRT branch parallelism for private operations, moving PSS Sign and OAEP Decrypt to GOOD-or-better against OpenSSL 3.6.0 in the v9.5.0 best-of-4 benchmark validation.
- Refreshed README/PyPI performance data: SHA-256, BLAKE2b, HMAC-SHA256, SHA-512, HMAC-SHA512, and RSA-3072 target rows now reflect current GOOD-or-better measurements.

### v9.4.0 (2026-05)
- Added a build-time OpenSSL perlasm-derived x86_64 SHA-512 AVX2/BMI2 block-compression path with kctsb symbol namespace rewriting and runtime CPUID/XCR0 gating.
- Kept the C++ WK3 SHA-512 fallback for hosts without the required AVX2/BMI1/BMI2 state while preserving SHA-512 digest, HMAC, padding, and public API semantics.
- Refreshed OpenSSL 3.6.0 benchmark data: SHA-512 1MB/10MB and HMAC-SHA512 1MB/10MB report `0.72x/0.99x/0.99x/1.06x` GOOD-or-better in the final v9.4.0 banner validation.

### v9.3.1 (2026-05)
- Added an independent AVX2 vertical 8-lane ChaCha20 bulk kernel with 8×8 transpose and 256-bit XOR/store output for large one-shot AEAD encryption.
- Retuned ChaCha20-Poly1305 one-shot Encrypt→MAC scheduling to 1 MiB L2-sized chunks and direct one-time Poly1305 key block generation while keeping RFC 8439 ciphertext/tag semantics unchanged.
- Refreshed OpenSSL 3.6.0 benchmark data: ChaCha20-Poly1305 1KB `1.06x` GOOD, 1MB `1.03x` GOOD, 10MB `1.00x` GOOD.

### v9.3.0 (2026-05)
- Fixed the Poly1305 AVX2 4-lane large-update merge by applying explicit lane weights (`r^4/r^3/r^2/r`) and normalizing post-add carries before radix conversion; this closes a large streaming-vs-one-shot tag equivalence gap.
- Added large Poly1305 bulk-vs-r44-chunked and streaming ChaCha20-Poly1305-vs-one-shot regression coverage while preserving RFC 8439 ciphertext/tag semantics.
- Switched one-shot ChaCha20-Poly1305 encrypt/decrypt for ≥4 KiB payloads to a ChaCha20 AVX2 + corrected Poly1305 AVX2 two-pass bulk path; final v9.3.0 OpenSSL benchmark复核: 1KB `1.05x` GOOD, 1MB `1.38x`, 10MB `1.20x` OK.

### v9.2.2 (2026-05)
- Stabilized `benchmark_suite.exe seal` on Windows/MinGW by running SEAL comparison last and using a benchmark-only fast exit after flushing the final report, avoiding SEAL 4.1.2 global memory-pool static teardown heap aborts without changing production crypto/FHE APIs.
- Extended default BFV HPSOverQ auto scheduling to verified `n=8192..32768,L>=3,size-2` multiply cases and skipped unused CUDA/BEHZ provider initialization when the default path is HPSOverQ; forced modes `hps_overq|hps|behz` remain available.
- Refreshed SEAL head-to-head data: BFV n=16384/L=5 Multiply `9.295 ms` vs SEAL `17.580 ms` (`0.53x` EXCELLENT), BFV n=32768/L=8 Multiply `35.178 ms` vs `66.470 ms` (`0.53x` EXCELLENT), CKKS n=16384/L=3 Multiply `0.378 ms` vs `0.513 ms` (`0.74x` EXCELLENT).
- Added a n=16384/L=5 default-auto vs forced-HPSOverQ correctness regression while preserving modulus, plaintext modulus, secret distribution, noise sampling, and provider fail-closed boundaries.

### v9.2.1 (2026-05)
- Optimized BFV HPSOverQ n=8192 size-2 multiply with L≥3 parallel input INTT, per-operand extension buffers, parallel Q/R extension+NTT, and per-tensor final rescale scheduling.
- Refreshed measured FHE data: focused n=8192/L=5 raw Multiply is now EXCELLENT (`5.233–6.199 ms` in final confirmation runs), and benchmark_suite n=8192/L=3 raw Multiply reached `0.72x` vs SEAL.
- Preserved security parameters and rollback controls: `KCTSB_BFV_MULTIPLY_MODE=hps_overq|hps|behz` remains available and CUDA provider ABI stays `0x00090102`.

### v9.1.0 (2026-05)
- Real CUDA acceleration for `kctsb_sha3_256_batch()` and `kctsb_blake2b_batch()` via new SHA3-256 + BLAKE2b GPU kernels (`cuda_hash_sha3_blake2b.cu`); provider ABI extended additively (`KCTSB_CUDA_API_VERSION = 0x00090100`).
- `kctsb_accel_select_crypto()` now returns CUDA for SHA3-256/BLAKE2b when `batch_count >= 32 || data_size >= 256 KiB`, with deterministic CPU fallback on any provider error.
- FHE auto-dispatch threshold tightened: `kctsb_accel_select_fhe()` requires `n >= 16384` or `(n >= 8192 && L >= 6)` for GPU, ensuring small-`n`/small-`L` BFV/BGV stays on the now-Harvey-NTT-optimized CPU path.
- SM3 inner compress: rounds 16-63 fully unrolled with `#pragma GCC unroll`, removing residual loop branch overhead.
- SHA-512 multi-block transform: tiered prefetch — 8-block lookahead for messages ≥ 16 blocks (≥ 2 KiB), preserving 4-block schedule for smaller inputs.
- Test surface expanded to 471 (added GPU↔CPU bit-exact equivalence for SHA3-256 / BLAKE2b batch); Release CTest 471/471 green.

### v9.0.1 (2026-05)
- Completed production primitive hardening for Groth16/QAP, BN254 Fp2/G2/Fp12 paths, BFV/BGV CRT decryption, SPDZ2k 104-bit MACs, ML-DSA signing/verification, NTT cache synchronization, and CKKS real rescale benchmark paths.
- Replaced BFV/BGV decrypt fallback dynamic big-integer reconstruction with fixed-limb CRT using the unified 128-bit arithmetic policy, while preserving the BEHZ RNS-native hot path.
- Added public `kctsb_sm3_batch()` coverage through the C API and benchmark suite; GPU auto-dispatch uses a real loaded CUDA provider only, otherwise AVX2/CPU fallback remains deterministic.
- Synchronized CUDA provider CMake/API metadata to v9.0.1 and constrained production auto-dispatch to audited FHE/NTT/PIR/hash paths; provider-only AES/SM4 CTR and ECC/SM2 scalar kernels remain benchmark/test artifacts, not public AEAD or secret-scalar replacements.
- PIR CUDA/preprocessing provider-unavailable paths now fail closed with security-policy semantics, because plaintext index fallback is unsafe.
- Removed deterministic emergency ML-DSA signatures and local placeholder proof/circuit paths where a secure implementation is available.
- Verified Release and Debug CTest suites: 469/469 tests passed in both configurations.

### v9.0.0 (2026-05)
- Hardened project-wide randomness paths to use kctsb platform CSPRNG for HCC blinding/DP noise, MPC MAC checks/triples/shares, ZK scalar sampling, SSE/OPE key and range sampling, and FHE C ABI RNG seeding.
- Verified Debug and Release CMake presets with `KCTSB_WARNINGS_AS_ERRORS=ON` and synchronized C++/pybind11/PyPI version metadata.
- Updated publishing validation for major-version release-note archives such as `docs/releases/V9Release/v9.0.0-release.md`.


## License
Apache-2.0 — Copyright (c) 2019-2026 knightc
