enigma-simulator

This enigma-simulator project is an educational tool which simulates the workings of an Enigma machine, the Germans' main military encryption tool during World War II. The software allows users to encrypt and decrypt messages. Additionally, the simulation includes a step-by-step guide that teaches users how to recover Enigma keys.

This project was created and maintained by the National Security Agency.

Enigma-Machine-Sim-1-23-2026.mp4

Usage

Command‑Line Interface

The core Enigma machine is implemented in Python modules machine.py and components.py. You can use it directly in Python:

from machine import Enigma
e = Enigma(key='AAA', swaps=['AB', 'CD'], rotor_order=['I', 'II', 'III'])
cipher = e.encipher('HELLO')

Graphical User Interface (GUI)

A standalone Tkinter‑based GUI is provided for interactive operation.

Prerequisites:

• Python 3.6+
• Tkinter (usually included with Python)

Setup:

1. Create a virtual environment (optional but recommended):

   python -m venv venv
   venv\Scripts\activate      # Windows
   source venv/bin/activate   # Linux/Mac

2. Install the package in development mode:

   pip install -e .

Launch the GUI:

python enigma_main_app.pygui

The GUI window will appear with the following controls:

• Rotor Order: dropdowns for left, middle, and right rotors (I, II, III, V)
• Rotor Positions: three‑letter initial setting (e.g., AAA)
• Plugboard Swaps: space‑separated pairs (e.g., AB CD)
• Apply Configuration: applies the settings to the Enigma machine
• Tutorial: opens a step‑by‑step guide to using the simulator
• Input/Output text areas: type your plaintext or ciphertext, then press Encrypt or Decrypt

Jupyter Notebooks

The project includes two educational notebooks:

• BreakingEnigma.ipynb – step‑by‑step guide to breaking Enigma using Rejewski's method
• MasterEnigmaCracker.ipynb – advanced cracking exercises

To run the notebooks, install Jupyter (pip install notebook) and start the server:

jupyter notebook

Tests

Run the included unit tests to verify the installation:

python test_app.py
python test_gui.py   # launches the GUI briefly and checks for errors