⚛️ QbitStrike

Educational quantum cryptanalysis suite — Demonstrating Shor's and Grover's algorithms against classical cryptographic primitives.

---

📖 Overview

QbitStrike is an educational quantum computing project that simulates the impact of quantum algorithms on classical cryptography. It provides hands-on implementations of:

• Shor's Algorithm — factorizes RSA public key moduli to recover private key factors
• Grover's Algorithm — performs quantum-accelerated key search using a known plaintext/ciphertext pair

Circuits can be executed either on a local Aer simulator or on a real IBM Quantum QPU via the IBM Quantum Platform.

⚠️ This project is strictly educational. It targets toy-sized keys and is not capable of breaking real-world cryptographic systems.

---

✨ Features

• 🔐 RSA factorization via Shor's algorithm (from .pem public key)
• 🔍 XOR key recovery via Grover's algorithm (from .bin ciphertext + known plaintext)
• ☁️ IBM Quantum QPU support (--environment qpu)
• 📊 Auto-generated circuit diagrams and measurement histograms
• 📁 JSON result exports for each run
• 🔧 Configurable shots, qubits, and environment via CLI

---

📋 Requirements

• Python 3.10+
• An IBM Quantum account (only required for --environment qpu) — Register here

---

🚀 Installation

1. Clone the repository

git clone https://github.com/mateocallec/QbitStrike.git
cd QbitStrike

2. Create a virtual environment

python3 -m venv .venv
source .venv/bin/activate        # Linux / macOS
.venv\Scripts\activate           # Windows

3. Install dependencies

pip install -r requirements.txt

4. Configure your IBM API key (optional, QPU only)

Create a .env file at the project root:

IBM_API_KEY=your_ibm_api_key_here

---

🧪 Usage

All algorithms are launched through main.py.

General syntax

python3 main.py --alg <shor|grover> [options]

Options

Argument	Description	Default
--alg	Algorithm to run (shor or grover)	(required)
--pem	RSA public key .pem file (Shor only)	—
--ciphertext	Path to ciphertext .bin file (Grover only)	—
--plaintext	Known plaintext integer value (Grover only)	—
--a	Base value coprime with N (Shor, optional)	auto
--n_qubits	Number of qubits (Grover, optional)	auto
--shots	Number of simulator/QPU shots	1024
--environment	simulator or qpu	simulator

---

🔢 Shor's Algorithm — RSA factorization

# Using local simulator
python3 main.py --alg shor --pem tiny_rsa_public.pem

# Using IBM QPU
python3 main.py --alg shor --pem tiny_rsa_public.pem --environment qpu --shots 2048

---

🔍 Grover's Algorithm — Key search

Step 1 — Generate a toy key and ciphertext

python3 tools/generate_aes.py

This creates:

• tiny_aes_key.bin — the secret key (for manual verification)
• cipher.bin — the ciphertext
• cipher_meta.json — metadata (plaintext value, key size)

The script will output the exact command to run, e.g.:

[INFO] Run Grover with: python3 main.py --alg grover --plaintext 5 --ciphertext cipher.bin

Step 2 — Run Grover

# Using local simulator
python3 main.py --alg grover --plaintext 5 --ciphertext cipher.bin

# With custom shots
python3 main.py --alg grover --plaintext 5 --ciphertext cipher.bin --shots 2048

# Using IBM QPU
python3 main.py --alg grover --plaintext 5 --ciphertext cipher.bin --environment qpu

---

📁 Project Structure

QbitStrike/
├── main.py                  # Entry point — CLI launcher
├── requirements.txt         # Python dependencies
├── .env                     # IBM API key (not committed)
│
├── modules/
│   ├── shor.py              # Shor's algorithm implementation
│   └── grover.py            # Grover's algorithm implementation
│
├── tools/                   # Utility scripts for testing
│   └── generate_aes.py      # Toy key & ciphertext generator
│
├── documents/               # Documentation and example outputs
│
└── outputs/                 # Generated results (circuits, histograms, JSON)

---

📤 Outputs

Each run resets and populates the outputs/ folder with:

File	Description
*_circuit.png	Quantum circuit diagram
*_histogram.png	Measurement probability histogram
results.json	Full run results (counts, parameters, found key/factors)

---

🗂️ Project Documents

File	Description
CHANGELOG.md	Version history and release notes
ROADMAP.md	Planned features and future improvements
SECURITY.md	Security policy and vulnerability reporting
CONTRIBUTING.md	Contribution guidelines
CODE_OF_CONDUCT.md	Community standards and conduct policy

---

📜 License

This project is licensed under the French Patriot License.
See the LICENSE file for full terms.

---

📬 Contact

Mateo Callec — mateo@callec.net
GitHub: github.com/mateocallec/QbitStrike