Inspiration

Randomness is the quiet foundation of digital security. Cryptographic keys, authentication secrets, and nonces all depend on entropy that an attacker cannot predict. Most software still draws that entropy from classical sources OS entropy pools or pseudorandom generators while quantum mechanics offers a different idea: measurement of a carefully prepared quantum state can yield outcomes that are inherently probabilistic.

We were inspired by a gap we kept seeing in quantum demos: either the physics was beautiful but disconnected from any real security workflow, or the security claims were exciting but scientifically overstated. We wanted a project that would let beginners see a Hadamard measurement, let investigators compare quantum-simulator and classical randomness on equal footing, and still connect the learning experience to something familiar — a TOTP authenticator — without pretending that QRNG is post-quantum cryptography or that a simulator is a physical entropy source.

That tension-curiosity about quantum randomness, paired with a refusal to overclaim became QubitKey.


What it does

QubitKey is an open-source quantum entropy laboratory and authentication prototype built with IBM Qiskit. It lets you:

  1. Generate randomness from quantum circuits — prepare qubits in superposition with Hadamard gates, measure them, and turn bitstrings into numerical samples.
  2. Inspect entropy honestly — explore bit balance, histograms, run lengths, empirical Shannon entropy, autocorrelation, and goodness-of-fit diagnostics.
  3. Compare sources fairly — Qiskit Aer (simulator), Python random (PRNG), Python secrets (OS CSPRNG), and optionally IBM Quantum hardware when credentials and a real job are available.
  4. Try a practical authenticator — enroll a TOTP secret (via OS CSPRNG + a maintained RFC 6238 library), scan a QR code, and verify one-time passwords.
  5. Explore PQC separately (optional) — an isolated ML-DSA signature demo, clearly labelled as distinct from QRNG and TOTP.

The core experiment is simple and transparent. For a single qubit:

[ H|0\rangle = \frac{|0\rangle + |1\rangle}{\sqrt{2}} ]

Ideal measurement yields (0) or (1) with equal probability (\tfrac{1}{2}). Repeated shots produce datasets you can analyse — and every simulator run is labelled as educational simulation, not physical quantum entropy.

Live demo: https://qubitkey.vercel.app
API: https://qubitkey-backend.onrender.com


How we built it

We designed QubitKey as a modular stack with clear trust boundaries:

Layer Stack
Frontend React, Vite, JavaScript, Tailwind, Recharts
Backend Python 3.11+, FastAPI
Quantum Qiskit + Qiskit Aer (SamplerV2); optional IBM Quantum Runtime
Analysis NumPy, SciPy, pandas
Auth secrets (OS CSPRNG) + pyotp (TOTP) + QR provisioning
Hosting Vercel (SPA) + Render (API)
Research Jupyter notebook on Binder for reproducible experiments

Architecture in one glance: the React UI talks to FastAPI; FastAPI routes work through quantum adapters (Aer, optional IBM QPU), an analysis module, and a security module. Provenance is first-class: experiment responses carry source labels and caveats, and the IBM path never silently falls back to the simulator.

Key engineering choices we locked in early:

  • Simulator vs hardware isolation — missing credentials or QPU failure returns an explicit error; we do not fake hardware success.
  • Endianness correctness — Qiskit bitstrings are little-endian (qubit 0 rightmost); we unit-test conversion so integer samples are not silently biased.
  • Honest TOTP secrets — MVP authenticator secrets come from the OS CSPRNG, not from unvalidated simulator bits.
  • Ephemeral demo storage — in-memory stores with short TOTP TTL; no secrets in localStorage.
  • Contracts before code — frozen API schemas and ADRs so parallel work could stay coherent.

Challenges we ran into

1. Scientific honesty vs. “wow” marketing.
It is tempting to say “quantum-powered authentication.” We deliberately did not. QRNG ≠ post-quantum cryptography; TOTP ≠ quantum-resistant; passing statistical tests ≠ entropy certification. Encoding those caveats into UI, API responses, docs, and the demo script took more discipline than shipping a flashier claim.

2. Qiskit / IBM Runtime evolution.
Primitives, Sampler APIs, and IBM Runtime client behaviour have shifted across recent releases. We pinned known-good versions (qiskit, qiskit-aer, optional qiskit-ibm-runtime) and treated hardware as an optional adapter with explicit failure modes.

3. Fair comparison without false equivalence.
Comparing Aer, PRNG, and CSPRNG only makes sense at equal sample sizes with documented settings. We had to resist treating “looks random on a chart” as a security proof.

4. Bitstring → integer conversion pitfalls.
Wrong endianness quietly biases every derived integer. Getting qubit-0-rightmost conversion correct — and testing it — was a small detail with large integrity impact.

5. Hosting a quantum-capable API for judges.
Free-tier cold starts, CORS between Vercel and Render, and ephemeral in-memory state meant we had to document wake-up delays and design the demo so judges can succeed without IBM credentials or a local install.


Accomplishments that we're proud of

  • A zero-install hosted demo that walks from Hadamard measurement → entropy comparison → live TOTP enrollment in about eight minutes.
  • Provenance as a product feature — every experiment is labelled; simulator and hardware paths cannot be confused by accident.
  • A threat model and methodology docs written for the same audience as the UI, not buried as afterthoughts.
  • Reproducible research path via Binder notebook, independent of the hosted API.
  • An architecture that keeps QRNG, TOTP, and ML-DSA conceptually separate — the distinctions judges care about are visible in the product, not only in the README.
  • Tests, CI, OpenAPI docs, and a release checklist aimed at fresh-clone and hosted verification.

What we learned

  • Measurement is pedagogy. Showing (H|0\rangle) and a shot histogram teaches more than a paragraph about “quantum randomness.”
  • Entropy education needs negative space. Saying what the system is not (certified QRNG, PQC authenticator, production entropy service) builds more trust than stacking superlatives.
  • Security demos should use maintained crypto. Reaching for OS CSPRNG + pyotp was the right MVP call; injecting simulator bits into key material would have been a scientific and ethical mistake.
  • Contracts unlock speed. Frozen schemas and ADRs let us build frontend, quantum engine, and auth in parallel without constant breakage.
  • Deployment is part of the experiment. Cold starts, CORS, and ephemeral stores are not “ops trivia” — they shape what a judge can actually verify in a timed window.

What's next for QubitKey

QubitKey → Quantum Entropy. Stronger Digital Identity.

Next steps we want to pursue:

  1. Verified IBM QPU runs with job metadata surfaced in the UI — physical measurement data, never silently substituted.
  2. Richer educational analytics — clearer explanations of what each diagnostic can and cannot conclude about randomness quality.
  3. Deeper PQC exploration — expand the isolated ML-DSA path as a teaching tool for quantum-resistant signatures, still kept separate from QRNG and TOTP.
  4. Better reproducibility tooling — exportable experiment reports and pinned notebook environments for classroom use.
  5. Hardening the demo path — without pretending to be a production entropy service: clearer rate limits, safer enrollment UX, and optional durable storage only if we can do it without false security theatre.

Our north star stays the same: make quantum entropy inspectable, comparable, and honest — then connect that learning to digital identity without overselling the physics.

Built With

Share this project:

Updates

Submission history