Skip to content

QDaria/zipminator

BranchesTags

Repository files navigation

Zipminator

Zipminator

Post-quantum cryptography toolkit with real quantum entropy
CRYSTALS-Kyber-768 (ML-KEM) in Rust, exposed as a Python SDK with 10-level data anonymization,
PII scanning, and quantum-seeded key generation from IBM Quantum hardware.

CI FIPS 203 Tests License Python Rust

What This Is

Zipminator is the open-source cryptographic core of the Zipminator PQC Platform. It provides:

  • Rust Kyber768 engine with constant-time arithmetic, NIST KAT validation, and fuzz testing
  • Python SDK (v0.5.0b1) with PyO3 bindings, 10-level anonymization, PII scanning, and CLI
  • Quantum entropy harvester that continuously collects real entropy from IBM Quantum (Fez, Marrakesh) via qBraid
  • Subscription-gated access with freemium L1-3 and API-key-gated L4-10

The commercial platform (Flutter super-app, Tauri browser, web dashboard) is built on top of this core but is not included in this repository.

Quick Start

pip install zipminator
from zipminator import keypair, encapsulate, decapsulate

# Generate a Kyber768 keypair (NIST FIPS 203, Security Level 3)
pk, sk = keypair()

# Encapsulate: sender creates shared secret + ciphertext
ct, shared_secret = encapsulate(pk)

# Decapsulate: receiver recovers the same shared secret
recovered = decapsulate(ct, sk)

assert shared_secret == recovered  # 32-byte shared secret

With quantum entropy seeding:

from zipminator.crypto.pqc import PQC

seed = open("quantum_entropy/quantum_entropy_pool.bin", "rb").read(32)
pqc = PQC(level=768)
pk, sk = pqc.generate_keypair(seed=seed)  # Seeded from IBM Quantum hardware

Features

Rust Kyber768 Core

From-scratch CRYSTALS-Kyber-768 in Rust. All secret-dependent operations use constant-time arithmetic via the subtle crate. Montgomery and Barrett reductions in the NTT layer. Compiles to both a native library and a Python extension module via PyO3/maturin.

Key sizes: PK = 1,184 bytes, SK = 2,400 bytes, CT = 1,088 bytes, SS = 32 bytes.

10-Level Data Anonymization

Progressive anonymization from basic masking to homomorphic encryption:

Level Technique Tier
L1 SHA-256 hashing Free
L2 Quantum-random replacement Free
L3 Deterministic tokenization Free
L4 Generalization (numeric ranges, categories) Developer
L5 Suppression (NULL replacement) Developer
L6 Quantum noise injection Pro
L7 Synthetic data generation (Faker) Pro
L8 k-Anonymity grouping Enterprise
L9 Differential privacy (Laplace noise) Enterprise
L10 Paillier homomorphic encryption Enterprise

PII Scanner

Automatic detection of 18+ PII types across Norwegian, US, and European jurisdictions. Each match gets a confidence score and risk level (low / medium / high / critical).

from zipminator.crypto.pii_scanner import PIIScanner
import pandas as pd

scanner = PIIScanner()
results = scanner.scan_dataframe(pd.read_csv("data.csv"))
print(results["summary"])
# PII Scan Results:
#   - 3 column(s) contain PII
#   - Risk Level: HIGH
#   - Recommended Anonymization Level: 7/10

Detected types include: Norwegian FNR, email, phone, SSN, credit card, IBAN, API keys, auth tokens, passwords, IP addresses, and more.

Quantum Entropy Harvester

Continuously collects real quantum entropy from IBM Quantum hardware (156-qubit Eagle r3 processors) via qBraid. The pool file grows without limit; consumers read from it dynamically.

# Daemon mode (runs forever, harvests every hour)
python -m zipminator.entropy.scheduler --daemon --interval 3600

# One-shot (for cron jobs)
python -m zipminator.entropy.scheduler --once

# Check pool status
python -m zipminator.entropy.scheduler --stats

Entropy quotas are managed per subscription tier:

Tier Monthly Entropy Overage
Free 1 MB $0.01/KB
Developer 10 MB $0.01/KB
Pro 100 MB $0.01/KB
Enterprise Unlimited -

Quantum Random Module

Drop-in replacement for Python's random module, backed by quantum entropy when available:

from zipminator.crypto.quantum_random import QuantumRandom

qr = QuantumRandom()
qr.random()              # float in [0.0, 1.0)
qr.randint(1, 100)       # inclusive range
qr.randbytes(32)         # cryptographic bytes
qr.choice(["a", "b"])    # random selection
qr.shuffle(my_list)      # Fisher-Yates shuffle

Self-Destruct

DoD 5220.22-M 3-pass overwrite (zeros, ones, random) with timer-based auto-destruct and audit logging.

CLI

pip install zipminator[cli]

zipminator keygen --output-dir ./keys
zipminator keygen --entropy-file quantum_entropy/quantum_entropy_pool.bin
zipminator entropy --bits 256

Architecture

                    +-----------------+
                    |   Python SDK    |  zipminator v0.5.0b1
                    |  CLI / Jupyter  |
                    +--------+--------+
                             |  PyO3
                    +--------+--------+
                    |   Rust Core     |  crates/zipminator-core
                    |  Kyber768 KEM   |
                    |  NTT / Poly     |
                    |  Entropy Pool   |
                    +--------+--------+
                             |
              +--------------+--------------+
              |              |              |
        +-----+----+  +-----+----+  +------+-----+
        | IBM Fez   |  | IBM      |  | OS Entropy |
        | (qBraid)  |  | Marrakesh|  | (fallback) |
        +-----------+  +----------+  +------------+

Repository Structure

zipminator/
+-- crates/
|   +-- zipminator-core/          Kyber768 KEM, NTT, poly, entropy pool, PyO3 bindings
|   +-- zipminator-fuzz/          cargo-fuzz targets (keygen, encaps, decaps, round-trip)
|   +-- zipminator-nist/          NIST FIPS 203 Known Answer Test runner
|   +-- zipminator-mesh/          Q-Mesh security (HMAC-SHA256 beacon auth)
|   +-- zipminator-app/           Flutter Rust Bridge (FRB) safe wrappers
+-- src/zipminator/               Python SDK
|   +-- crypto/                   PQC wrapper, PII scanner, anonymization, self-destruct
|   +-- entropy/                  Provider adapters, scheduler daemon, quota manager
|   +-- jupyter/                  JupyterLab magics and widgets
+-- tests/
|   +-- python/                   162 tests (core, PQC, subscription, PII, entropy)
+-- scripts/
|   +-- qrng_harvester.py         Standalone entropy harvester
+-- quantum_entropy/              Entropy pool (gitignored .bin files)
+-- config/                       Provider YAML configs

Installation

From PyPI

pip install zipminator                          # Core (894KB wheel, Rust crypto included)
pip install zipminator[cli]                     # + CLI (typer, rich)
pip install zipminator[data]                    # + numpy, pandas, pyzipper
pip install zipminator[anonymization]           # + faker, numpy, pandas
pip install zipminator[jupyter]                 # + JupyterLab, ipywidgets, plotly
pip install zipminator[all]                     # Everything

From Source

Requirements: Rust 1.70+, Python 3.9+.

git clone https://github.com/QDaria/zipminator.git
cd zipminator

# Build Rust core + Python bindings
pip install maturin
maturin develop --release --strip

# Install with dev dependencies
pip install -e ".[dev,data,anonymization,cli]"

# Run tests
cargo test --workspace                          # 413 Rust tests
pytest tests/python/ -v                         # 162 Python tests

Security

NIST FIPS 203 (ML-KEM)

The Kyber768 implementation follows the NIST FIPS 203 specification. Validation is performed against the official Known Answer Test vectors via a deterministic DRBG.

cd crates/zipminator-nist
cargo test

Note: This library implements FIPS 203 (the algorithm specification). It has not undergone FIPS 140-3 module validation (which requires CMVP certification). Do not represent this as "FIPS certified" or "FIPS validated."

Constant-Time Operations

All secret-dependent operations use:

  • subtle::ConstantTimeEq for key comparison
  • subtle::ConditionallySelectable for branch-free secret selection
  • csubq() with arithmetic masking (no conditional branches)
  • Montgomery and Barrett reductions as #[inline(always)]

Fuzz Testing

Four cargo-fuzz targets cover the attack surface:

Target Input
fuzz_keygen Arbitrary seed bytes
fuzz_encapsulate Malformed public keys
fuzz_decapsulate Malformed ciphertext/key pairs
fuzz_round_trip End-to-end correctness 
cd crates/zipminator-fuzz
cargo fuzz run fuzz_keygen -- -max_total_time=300

Test Coverage

Layer Tests Status
Rust core (Kyber768, anonymize, ratchet, SRTP, email) 200 Passing
Rust browser (Tauri, prompt guard) 125 Passing
Rust NIST KAT 35 Passing
Rust mesh (HMAC-SHA256 beacon auth) 28 Passing
Rust bridge (FRB) 25 Passing
Total Rust 413 Passing
Python core (Kyber bindings, PQC wrapper) 73 Passing
Python subscription (tiers, API key gating) 35 Passing
Python entropy (quota, scheduler) 20 Passing
Python quantum random 18 Passing
Python PII scanner 10 Passing
Python multi-provider 16 Skipped (needs external deps)
Total Python 162 Passing
Grand Total 575

Benchmarks

Measured via the Python SDK (PyO3 bindings) on Apple M1 Max, release build. Native Rust performance is higher; these numbers include Python-Rust bridge overhead.

Operation ops/sec Latency
KeyGen 3,115 321 us
Encapsulate 1,649 607 us
Decapsulate 1,612 620 us
Full Round Trip 900 1.1 ms

Run benchmarks locally:

# Rust-native benchmarks (Criterion)
cd crates/zipminator-core && cargo bench

# Python SDK benchmarks
python -c "
from zipminator._core import keypair, encapsulate, decapsulate
import time
pk, sk = keypair()
start = time.perf_counter()
for _ in range(1000):
    ct, ss = encapsulate(pk)
    decapsulate(ct, sk)
print(f'{1000/(time.perf_counter()-start):.0f} round-trips/sec')
"

Quantum Entropy Providers

Provider Backend Status
qBraid IBM Fez / Marrakesh (156-qubit Eagle r3) Production
IBM Quantum Qiskit Runtime Available
Rigetti QCS (pyQuil) Available
OS Fallback getrandom / os.urandom Always available 
# .env
QBRAID_API_KEY=your_key
IBM_QUANTUM_TOKEN=your_token
RIGETTI_API_KEY=your_key

The harvester daemon continuously pulls entropy into an ever-growing pool:

# Crontab: harvest every 6 hours
0 */6 * * * /path/to/python -m zipminator.entropy.scheduler --once

Subscription Tiers

The open-source SDK includes all 10 anonymization levels. Levels 1-3 are always available. Levels 4-10 require an API key or activation code.

Tier Price Levels Entropy QRNG
Free $0 1-3 1 MB/mo No
Developer $9/mo 1-5 10 MB/mo No
Pro $29/mo 1-7 100 MB/mo No
Enterprise Custom 1-10 Unlimited Yes 
from zipminator.crypto.subscription import APIKeyValidator

# L1-3: always works
allowed, msg, method = APIKeyValidator.authorize_level(3)
assert allowed  # True, free_tier

# L4+: needs API key or activation code
import os
os.environ["ZIPMINATOR_API_KEY"] = "your-key"
allowed, msg, method = APIKeyValidator.authorize_level(7)

Open Source vs Enterprise

Component This Repo Enterprise
Rust Kyber768 core Yes Yes
Python SDK + CLI Yes Yes
10-level anonymization Yes Yes
PII scanner Yes Yes
Quantum entropy harvester Yes Yes
Entropy quotas + billing Yes Yes
NIST KAT + fuzz testing Yes Yes
Flutter super-app (iOS/Android/macOS/Windows/Linux) - Yes
Tauri PQC browser (ZipBrowser) - Yes
Web dashboard + pitch deck - Yes
PQC Messenger + VoIP - Yes
Q-VPN (PQ-WireGuard) - Yes
Quantum Mail (@zipminator.zip) - Yes
HSM integration - Yes
FIPS 140-3 validated module - Yes
SSO / RBAC - Yes
24/7 support + SLA - Yes

Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feat/your-feature)
  3. Run the quality gates: 
    cargo test --workspace
cargo clippy --all-targets -- -D warnings
pytest tests/python/
ruff check src/
  4. Submit a pull request

All PRs must pass CI: clippy clean, ruff clean, tests green.

License

Copyright 2025-2026 QDaria AS

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Enterprise features (Flutter apps, browser, VPN, mail, HSM, SSO) require a separate commercial license. Contact enterprise@zipminator.zip.

Links

Built by QDaria in Oslo, Norway.

About

Post-quantum cryptography toolkit: Rust Kyber768 (NIST FIPS 203) + Python SDK with 10-level anonymization, PII scanning, and quantum entropy from IBM Quantum hardware

Topics

python rust cryptography quantum-computing post-quantum-cryptography data-anonymization pqc ml-kem kyber768 nist-fips-203

Resources

Readme

License

Apache-2.0 license
Activity
Custom properties

Stars

1 star

Watchers

1 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages