Metadata-Version: 2.4
Name: kctsb
Version: 8.6.1
Summary: High-performance cryptographic library — HE (CKKS/BFV/BGV), DP, PSI/PIR, VOPRF, SSS, MPC, 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,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
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"

# kctsb — Knight's Cryptographic Trusted Security Base

High-performance cryptographic library with Python bindings for homomorphic encryption, differential privacy, private set intersection, MPC, and encrypted ML inference.

**Current release: v8.6.1** — adds `kctsb.crypto` atomic primitives (hardware-accelerated AES-GCM, ChaCha20-Poly1305, SHA-2/SHA-3, HMAC, HKDF, CSPRNG) exposed directly from the C++ core. Enables full crypto-stack replacement: eliminate `hashlib` / `hmac` / `secrets` / `cryptography` from user code and drive every primitive through the same AES-NI / SHA-NI / AVX2 / CUDA-capable engine as CKKS / PIR / MPC.

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

## Features

| Module | Description |
|--------|-------------|
| `kctsb.crypto` | **NEW v8.6.1** — atomic primitives: AES-GCM (AES-NI), ChaCha20-Poly1305, SHA-256/512/3 (SHA-NI), HMAC, HKDF, constant-time CSPRNG, `secure_compare`; `hashlib`/`hmac`/`secrets`-compatible shims (`_hashlib`, `_hmac`, `token_bytes`, `token_hex`) |
| `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 (Piano-PSI, OT-PSI with IKNP/KKRT) |
| `kctsb.pir` | Private Information Retrieval (FHE-based, BGV/BFV/CKKS) |
| `kctsb.voprf` | RFC 9497 VOPRF (P256-SHA256, OPRF/VOPRF/POPRF modes) |
| `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.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 (NEW in v8.6.1)

Hardware-accelerated replacements for `hashlib` / `hmac` / `secrets` / `cryptography.AESGCM`:

```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)

# Drop-in stdlib compatibility (no source changes needed):
from kctsb.crypto import _hashlib as hashlib   # replaces `import hashlib`
from kctsb.crypto import _hmac    as hmac      # replaces `import hmac`
from kctsb import crypto          as secrets   # replaces `import secrets`
```

### 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
```

## License

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