🔐 MiniRSA Breaker

Category: Cryptography / Educational Visualization
Tech Stack: Python · PyQt6
Author: Justin Guida
White Hat Verified 🧢

Overview

MiniRSA Breaker is an interactive desktop application that demonstrates how RSA encryption and decryption work through clear, visual, and mathematical explanations.
It provides step-by-step feedback for every stage of the process, prime generation, key computation, and ciphertext decoding, allowing learners to see how real cryptographic logic operates.

Build understanding through math, logic, and real cryptographic theory. All students and educators welcome.

Use it to:

• Teach RSA key concepts
• Break down modular exponentiation
• Compare weak vs. strong keys

Whether you're a teacher, a CS student,or just someone fascinated by how passwords work, this tool was built for you.

Features

RSA Key Generation
Generate custom or random small prime keys instantly.

Modular Exponentiation Engine
Performs c = m^e mod n and m = c^d mod n using Python’s pow() function, real, fast RSA behavior.

Character Mapping System
Maps characters A–Z to integers 01–26, with optional symbol support for extended messages.

Encryption & Decryption Panels
Visualize the full message transformation — from plaintext to ciphertext and back, in real time.

Step-by-Step Math Breakdown
Each stage of RSA math is clearly explained and animated for learning purposes.

Error Handling + Input Validation
Smart checks catch invalid primes, characters, and unsupported input types, with helpful messages.

100% Offline Application
Runs entirely on your device , no web server, no uploads, just fast, secure local computation.

Debug Mode & Educational Hints
Toggle debug mode to show raw values, intermediate results, and contextual explanations at every step.

Screenshots

Main Interface RSA Setup:

Define primes, generate public/private keys, and view entropy ratings in real time.

Encryption Panel:

Watch your message get encrypted character by character using modular exponentiation.

Decryption Panel:

Reverse the cipher text and view RSA logic in reverse using your private key

How to Run:.

Follow these steps to launch MiniRSA_Breaker locally:

1. Clone the Repository

git clone https://github.com/jguida941/MiniRSA_Breaker.git
cd MiniRSA_Breaker

2. Create a virtual environment (recommended)

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies

pip install -r requirements.txt

4. Launch the app

python rsa.py

Quality & Testing Pipeline

Run the full local quality stack (matches CI gates):

pip install -e .[dev,gui]
pip install pre-commit && pre-commit install
make quality

Targeted checks (see docs/ai-assisted-quality-playbook.md for the full workflow):

• For Codex or fully automated runs without Docker, follow docs/codex-integration.md or simply execute make codex-pipeline (JSON summary is written to codex-report.json).
• ruff check . – static analysis that catches unused imports, undefined names, and formatting drift before runtime.
• mypy src/mini_rsa – strict typing on the math engine to surface AI-generated signature mismatches or accidental Any.
• pytest -m "gui" – headless Qt smoke tests (use xvfb-run on Linux) to verify signal wiring and background threads.
• pytest tests/unit/test_imports.py – import smoke to expose circular imports or optional dependency slips.
• mutmut run --paths-to-mutate src/mini_rsa – mutation testing to prove the unit/property tests kill realistic math regressions.
• bandit -q -r src/mini_rsa rsa.py – security linting for unsafe randomness, subprocess usage, or crypto misconfigurations.
• pip-audit -r requirements.txt – dependency vulnerability scan so nightly AI updates do not introduce known CVEs.
• make mutation MUTATE_PATHS=src/mini_rsa/core.py – quick scoped mutation sweep before merging AI-generated core edits.
• make mutation-clean – clear cached Hypothesis/Mutmut artefacts if diffs get noisy.
• pre-commit run --all-files – mirror the lint/type/security checks that run automatically on every commit.

License

Evaluation only - all rights reserved.

You may clone and run locally for personal or hiring evaluation.
You may not redistribute, sublicense, or use this work commercially without my written permission.

See the LICENSE file for the exact terms.

Qt note: This app uses PyQt6 (GPLv3). Do not redistribute the app unless you comply with GPLv3 or have a Qt commercial license.

Educational Use Terms

• Use this tool in lessons, demos, or assignments
• Modify and explore it freely for academic learning
• Ensure visible credit appears in repurposed or adapted materials

Learn from the Best:

• FreeCodeCamp: Scientific Python
• Harvard CS50x 2024
• Cryptographic Methods