qiskit-qkd-lab

A QKD protocol simulator built directly on Qiskit primitives. Circuits run unchanged on AerSimulator or on real IBM Quantum hardware — including Eve's eavesdropping, which is implemented as genuine circuit operations (mid-circuit measurement + reset + conditional re-prep), not a statevector shortcut.

Installation

pip install qiskit-qkd-lab

Requires Qiskit 2.0 or later. For local development or to run the test suite:

git clone https://github.com/RexRowan/qiskit-qkd-lab.git
cd qiskit-qkd-lab
pip install -e ".[dev]"
pytest

Quick start (Colab)

from qiskit_qkd_lab.protocols import bb84
from qiskit_qkd_lab.channel.eavesdrop import InterceptResend
from qiskit_qkd_lab.diagnostics.qber import estimate_qber, key_rate_report

Or just run examples/demo_bb84.py directly — it's self-contained and prints a QBER report for clean, fully-intercepted, and partially-intercepted channels.

See docs/api.md for the full API reference and a runnable end-to-end example.

Status

This package implements the measurement and diagnostics half of BB84. Implemented so far:

• BB84 prepare/measure circuits (Z/X basis)
• Intercept-resend eavesdropper, circuit-level (mid-circuit measurement)
• Sifting
• QBER estimation via public sample comparison
• Basic key-rate / Eve-detection report
• Test suite + CI (Python 3.10–3.13)

Not yet implemented:

• E91 (entanglement-based) protocol
• Beam-splitting eavesdropper
• Cascade error reconciliation (currently we just sacrifice bits to estimate QBER; there's no actual error-correction step reconciling the retained key yet)
• Privacy amplification (universal hashing)
• Realistic channel noise model (fiber loss / detector dark counts)
• Live diagnostics dashboard (QBER vs. sample size, key rate vs. distance) — reusing patterns from qiskit-sqd-dashboard

Because reconciliation and privacy amplification aren't implemented yet, the "final key" this package produces is a sifted, QBER-estimated bit string, not a cryptographically secure key. It's a faithful simulator of BB84's quantum layer and QBER-based eavesdropping detection, useful for teaching and prototyping — treat it accordingly until those pieces land.

See CHANGELOG.md for release history and the roadmap.

Design notes

• Eve's classical register (eve) is entirely separate from Alice/Bob's shared register (c) — Bob's measurement pipeline never touches it, which is what makes this a faithful "Eve is undetectable except through QBER" model rather than a leak.
• InterceptResend(p_intercept=...) lets you sweep partial interception to reproduce the textbook QBER-vs-intercept-rate curve, rather than only the full-intercept extreme.
• n_qubits in the demo means independent single-photon sends batched into one circuit for simulation speed — no entangling gates between them, so this maps directly onto real hardware qubit count budgets.

Contributing

Contributions are welcome — see CONTRIBUTING.md for setup instructions, style guidelines, and the design principles this project tries to hold to. Please note this project follows the Contributor Covenant.

License

MIT