BB84 Quantum Key Distribution Simulator

A modular, containerized Python implementation of the BB84 protocol. This educational toolkit demonstrates how two parties (Alice and Bob) can establish a shared secret key and detect eavesdroppers (Eve) using the fundamental principles of quantum mechanics.

Key Features

• Dockerized Environment: Run instantly on any operating system without dependency conflicts
• Modular Architecture: Clean separation between quantum physics simulation (core.py) and protocol entities (actors.py)
• Interactive Configuration: Customizable simulation parameters for testing different attack scenarios
• Educational Visualization: Detailed, color-coded output showing each photon's journey through the protocol

Quick Start

Option 1: Docker (Recommended)

The simplest way to run the simulator without managing Python versions or dependencies:

# Build the container
docker build -t qkd-sim .

# Run the simulation
docker run -it qkd-sim

Note: The -it flag enables interactive input for configuration prompts.

Option 2: Local Installation

If you prefer running directly on your machine:

# Install dependencies
pip install -r requirements.txt

# Run from the project root directory
python -m src.main

Important: Execute this command from the qkd-sim/ root folder.

Project Structure

qkd-sim/
├── Dockerfile          # Container definition for cross-platform portability
├── requirements.txt    # Python package dependencies
├── src/
│   ├── main.py        # Orchestrator connecting Alice, Bob, and Eve
│   ├── core.py        # Physics engine for qubit measurement and collapse
│   ├── actors.py      # Protocol entities (Alice, Bob, Eve classes)
│   └── utils.py       # UI helpers, coloring, and configuration
└── README.md

Configuration Parameters

When launching the simulation, you'll configure these parameters:

Parameter	Description	Recommended Values
Photon Count	Number of qubits Alice sends to Bob	15 (demo), 100+ (statistics)
Enable Eve	Activate the eavesdropper	y to observe attacks
Eve Probability	Interception frequency (0.0-1.0)	0.3-0.7 for realistic scenarios
Decoy States	Protection against photon number splitting	y for enhanced security

Understanding the BB84 Protocol

The simulation executes in five distinct phases:

Phase 1: Alice Prepares Photons

Alice generates random bits and encodes them into quantum states using randomly chosen bases:

• Rectilinear Basis (+): 0° represents bit 0, 90° represents bit 1
• Diagonal Basis (×): 45° represents bit 0, 135° represents bit 1

Phase 2: Eve Intercepts (Optional Attack)

When enabled, Eve attempts to measure photons in transit:

• The Quantum Trap: Eve has a 50% chance of choosing the wrong measurement basis
• State Collapse: Wrong basis measurements disturb the quantum state, creating detectable errors
• Detection: These disturbances become visible during the error analysis phase

Phase 3: Bob Measures

Bob receives photons and measures them using his own random basis sequence:

• Basis Match: When Bob's basis matches Alice's, he recovers the correct bit (unless Eve interfered)
• Basis Mismatch: Wrong basis yields random results (50/50 probability)

Phase 4: Sifting (Public Reconciliation)

Alice and Bob publicly compare which bases they used (not the bit values):

• Matching bases: Bits are retained in the sifted key
• Mismatched bases: Bits are discarded

Critical Insight: The sifted keys should be identical. Any discrepancy indicates interception.

Phase 5: Error Analysis (Security Verification)

The Quantum Bit Error Rate (QBER) determines channel security:

Formula: QBER = (Number of Errors) / (Total Sifted Bits)

QBER Range	Interpretation	Action
0-2%	Secure channel	Proceed with key
2-10%	Suspicious activity	Caution advised
>11%	Active eavesdropping	Abort protocol

Experimental Scenarios

1. Baseline (Secure Channel)

• Configuration: Eve disabled
• Expected Result: QBER ≈ 0%, perfect key agreement

2. Passive Eavesdropping

• Configuration: Eve enabled, probability = 0.2
• Expected Result: QBER ≈ 5%, marginal detection threshold

3. Active Attack

• Configuration: Eve enabled, probability = 1.0
• Expected Result: QBER ≈ 25%, protocol abort triggered