Toolkit API

Reference for the seven modules under toolkit/: signatures, defaults, gotchas, and copy-paste call patterns.

Setup

All seven modules live at toolkit/*.py with no __init__.py — Python 3's implicit namespace packages make toolkit importable as a package as long as the repo root is on sys.path. There is no installed package; nothing is pip install -e'd.

# 1. venv
cd ~/LUME/qctf
source .venv/bin/activate    # or call .venv/bin/python directly

# 2. at the top of your solver script:
import sys
sys.path.insert(0, ".")
from toolkit import bb84, crypto_utils   # package style — matches module docstrings

# — or, bare-name style (matches how the modules import each other internally,
#   e.g. bb84.py does `from crypto_utils import bits_to_bytes, xor`) —
sys.path.insert(0, "toolkit")
import bb84, crypto_utils

Both forms were run from a script file outside the repo (cwd forced to the repo root) and both import and execute cleanly. A quick one-off in the interpreter or python -c also works without any path insert, because -c/stdin mode puts cwd on sys.path automatically — scripts saved to a .py file do not get that for free.

Self-test

./run_selftests.sh (from the repo root) runs every module's _selftest() via .venv/bin/python toolkit/<module>.py and prints the last line of each — green across the board means the toolkit is CTF-ready:

qsim:          qsim self-test OK
crypto_utils:  crypto_utils self-test OK
qasm_tools:    qasm_tools self-test OK (sample = 3 operative lines)
chsh:          chsh self-test OK (quantum 0.858 vs classical 0.750, Tsirelson 0.854)
bb84:          bb84 self-test OK (sifted 182/400 clean, Eve QBER 0.233)
algorithms:    algorithms self-test OK (grover -> 101, shor 3233 -> 61*53)
pqc:           pqc self-test OK (KEM ML-KEM-768 shared-secret match; SIG ML-DSA-65 verify+reject)

What each assert actually checks:

qsim

Thin Qiskit helpers used across every category that touches a circuit: build, run, inspect. Nothing category-specific — this is the base every other quantum module sits on.

from toolkit import qsim

qc = qsim.bell_pair()
print(qsim.show(qc))
counts = qsim.run_counts(qc, shots=2000)
print(counts)          # {'11': 1024, '00': 976}
sv = qsim.statevector(qc)
print(sv)               # Statevector([0.707+0j, 0, 0, 0.707+0j], dims=(2, 2))

crypto_utils

Classical glue for the "now decrypt the flag" finish that most quantum challenges end with — once you've recovered key bits from a BB84 transcript or a CHSH-style side channel, this turns them into bytes and runs the AES/XOR step so the quantum solver stays focused on the quantum part.

from toolkit import crypto_utils as cu

key = cu.bits_to_bytes("0100100001101001")   # b'Hi'
msg = b"flag{demo}"
ct = cu.xor(msg, key)
print(cu.b64(ct))                             # LgUpDjMNLQQnFA==
pt = cu.xor(cu.unb64(cu.b64(ct)), key)
print(pt)                                      # b'flag{demo}'

bb84

[Day 7] BB84 quantum key distribution — simulator and transcript solver. QKD category: given a captured transcript (Alice's bases, Bob's bases, Bob's measured bits) reconstruct the sifted shared key, and use QBER to detect an eavesdropper.

Transcript dataclass fields, for reference: alice_bits, alice_bases, bob_bases, bob_bits, eve_bases=None, sifted_positions=[], sifted_key=[].

CLI, for sifting a transcript straight from the shell without writing a script:

python toolkit/bb84.py --sift 0101 0011 1010
# prints the key from positions where alice_bases[i] == bob_bases[i]

from toolkit import bb84, crypto_utils as cu

t = bb84.simulate_bb84(n=512, seed=42)
key_bits = bb84.reconstruct_key(t.alice_bases, t.bob_bases, t.bob_bits)
print(len(key_bits))                 # 261
key_bytes = cu.bits_to_bytes(key_bits)

alice_sifted = [t.alice_bits[i] for i in t.sifted_positions]
print(bb84.qber(alice_sifted, key_bits))   # 0.0 (no Eve here)

chsh

[Day 6] CHSH game — Bell-pair strategy and win-rate checker. "Proof of entanglement" category: demonstrate or reproduce a win rate above the 0.75 classical ceiling.

Module-level constants worth knowing: ALICE_ANGLE = {0: 0.0, 1: pi/4}, BOB_ANGLE = {0: pi/8, 1: -pi/8}.

from toolkit import chsh

q = chsh.quantum_winrate(shots=4000)
c = chsh.classical_winrate()
print(f"quantum={q:.3f} classical={c:.3f}")   # quantum=0.849 classical=0.750

qasm_tools

[Day 5] OpenQASM load/emit plus a golf linter for "≤ N lines" budget challenges (e.g. an "XOR-bit-al"-style circuit-golf task). Loads QASM 2.0/3.0, counts the lines a golf challenge actually counts, and round-trips through the simulator so you can verify a golfed circuit still behaves the same.

from toolkit import qasm_tools as qt

sample = """OPENQASM 2.0;
include "qelib1.inc";
qreg q[2];
creg c[2];
h q[0];
cx q[0],q[1];
measure q -> c;
"""
qc = qt.load_qasm(sample)
print(qt.golf_report(sample, budget=3))
# 3 operative line(s) / budget 3 -> OK
#    1: h q[0];
#    2: cx q[0],q[1];
#    3: measure q -> c;
print(qt.gate_count(qc), qt.line_count(sample))   # 4 3

algorithms

[Days 9–10] Grover search and Shor-style factoring. Grover: "find the input that makes this predicate true" over a small search space. Shor: "factor this modulus" / "break this small RSA".

from toolkit import algorithms as alg

# targets are big-endian strings of width n
answer = alg.grover_search(["1011"], n=4)
print(answer)                       # '1011'

p, q = alg.shor_factor(3233)
print(p, q)                         # 61 53

pqc

Post-quantum crypto: Kyber/ML-KEM encapsulation and Dilithium/ML-DSA signatures, wrapping liboqs-python (import oqs). For the "recover the shared secret" or "forge/verify a signature" mechanics, so you can focus on the actual bug (nonce reuse, malformed ciphertext, key confusion, etc).

from toolkit import pqc

pk, sk = pqc.kyber_keypair()
ct, secret_enc = pqc.kyber_encaps(pk)
secret_dec = pqc.kyber_decaps(sk, ct)
print(secret_enc == secret_dec)     # True

vpk, vsk = pqc.dilithium_keypair()
msg = b"flag{pqc_demo}"
sig = pqc.dilithium_sign(vsk, msg)
print(pqc.dilithium_verify(vpk, msg, sig))        # True
print(pqc.dilithium_verify(vpk, msg + b"!", sig)) # False

Challenge shapes — end-to-end chains

Three complete, runnable scripts for the shapes these challenges actually take. Each was executed against the repo venv; output is shown as a comment where it matters. Run with cd ~/LUME/qctf && .venv/bin/python your_script.py.

1. BB84 transcript → sift → bytes → AES-CBC → flag

The captured transcript gives you alice_bases, bob_bases, bob_bits; the challenge ships an AES-CBC ciphertext + IV encrypted under the sifted key. This script fabricates a matching ciphertext with the simulator (a stand-in for what a challenge would hand you) and then does the actual solve: transcript → key → decrypt.

import sys
sys.path.insert(0, ".")
from toolkit import bb84, crypto_utils as cu
from Crypto.Cipher import AES
from Crypto.Util.Padding import pad, unpad

# --- stand-in for "the challenge hands you a transcript + ciphertext" ---
FLAG = b"flag{bb84_then_aes_cbc}"
t = bb84.simulate_bb84(n=1024, seed=99)
alice_bases, bob_bases, bob_bits = t.alice_bases, t.bob_bases, t.bob_bits

key_bits = bb84.reconstruct_key(alice_bases, bob_bases, bob_bits)
key = cu.bits_to_bytes(key_bits)[:16]
iv = bytes(16)
ciphertext = AES.new(key, AES.MODE_CBC, iv).encrypt(pad(FLAG, 16))

# --- the actual solve: recover the key from the transcript, decrypt ---
recovered_bits = bb84.reconstruct_key(alice_bases, bob_bases, bob_bits)
recovered_key = cu.bits_to_bytes(recovered_bits)[:16]
plaintext = unpad(cu.aes_decrypt(ciphertext, recovered_key, iv, mode="CBC"), 16)
print("recovered flag:", plaintext)
# recovered flag: b'flag{bb84_then_aes_cbc}'

2. QASM given → load_qasm → golf_report → shortened

A challenge gives you a QASM program and a line budget it's over. Load it, see which lines count, spot the redundancy (here: h q[0]; h q[0]; cancels to identity), golf it, and confirm the shortened version still measures the same.

import sys
sys.path.insert(0, ".")
from toolkit import qasm_tools as qt, qsim

given = """OPENQASM 2.0;
include "qelib1.inc";
qreg q[2];
creg c[2];
h q[0];
h q[0];
cx q[0],q[1];
measure q -> c;
"""
print(qt.golf_report(given, budget=3))
# 4 operative line(s) / budget 3 -> OVER
#    1: h q[0];
#    2: h q[0];
#    3: cx q[0],q[1];
#    4: measure q -> c;

golfed = """OPENQASM 2.0;
include "qelib1.inc";
qreg q[2];
creg c[2];
cx q[0],q[1];
measure q -> c;
"""
print(qt.golf_report(golfed, budget=3))
# 2 operative line(s) / budget 3 -> OK

# confirm the golfed circuit still behaves the same
print(qsim.run_counts(qt.load_qasm(given), shots=1000))   # {'00': 1000}
print(qsim.run_counts(qt.load_qasm(golfed), shots=1000))  # {'00': 1000}

3. Unknown predicate → phase_oracle (via grover_search) → answer

A challenge exposes a black-box predicate over an n-bit input and asks for the input that makes it true. Evaluate the predicate classically (or however the challenge lets you probe it) to build the target list, then let Grover pick it out of the search space.

import sys
sys.path.insert(0, ".")
from toolkit import algorithms as alg

def predicate(x: str) -> bool:
    return x == "1101"   # stand-in for a real black box

n = 4
targets = [format(v, f"0{n}b") for v in range(2 ** n) if predicate(format(v, f"0{n}b"))]
print("targets:", targets)          # targets: ['1101']

answer = alg.grover_search(targets, n=n, shots=2000)
print("recovered input:", answer)   # recovered input: 1101
assert predicate(answer)