Online Enigma Machine Emulator

Summer 2025 NAU CS315 Final Project Developed by Aiden Seay, Victor Rodriguez, and Nasya Valenzuela

Overview

This repository contains files to run an online enigma machine emulator. Users will be able to encode and decode secret messages accurate to the Enigma M3 series used by the Germans in WWII. This machine's encryption algorithm was broken by Alan Turing and his team at Bletchley Park.

Main Emulator Page

Configuration Page

Project Components

Message Encoding and Decoding

• Interactive user interface that allows users to input text and see their encoded or decoded message
• Physical keyboard support - Type directly on your keyboard for faster input
• Keyboard shortcuts: Enter to save, Escape to restart, Space for spaces
• Real-time rotor visualization - Watch the rotors turn as you type
• Automatic rotor reset - Rotors reset to initial positions after saving messages for proper decryption

Enigma Machine Configuration

• A page that will allow users to customize the machine state to create different encryption settings
• The configuration options include swapping rotors, 3 rotating rotors, and a plugboard
• Each configuration can be saved by the user for later use

Visual Encryption Steps

• As each key is pressed (on-screen or physical keyboard), the onscreen keyboard will light up the letter pressed and the letter it is encoded to
• The rotors will rotate realistically with each keypress
• Dual input methods: Use the on-screen keyboard or type directly on your physical keyboard

User Accounts and Saved Posts

• Users can create an account to save their encoded or decoded messages to their profile
• User accounts will have their passwords hashed in the database
• Users can save their favorite configurations

Manage Account

• Users can delete their saved messages and configurations
• Users can edit their saved machine configurations - Will not overwrite
• Comprehensive input validation - Ensures data integrity and security
• User-friendly error handling - Clear messages when something goes wrong
• Data integrity safeguards - Account deletion removes all user data (messages and configs)
• Cascading deletions - Deleting a configuration also removes all associated messages
• Transaction-based operations - Database operations use transactions to maintain consistency

Set up

Program Requirements

• NodeJS
• PostgreSQL
• React

Installation Steps

1. Clone the repository

git clone https://github.com/aidengseay/EnigmaMachine.git

2. Create a secrets.env file (more information below) inside the server folder

DB_USER={...}
DB_HOST={...}
DB_NAME={...}
DB_PASSWORD={...}
DB_PORT={...}

3. Start a Postgres server and make a database called EnigmaDB containing three tables and their respective columns below

Table	Column Name	Data Type	Constraints
users	user_id	SERIAL	PRIMARY KEY
	username	VARCHAR(50)	UNIQUE, NOT NULL
	password	VARCHAR(255)	NOT NULL
configs	config_id	SERIAL	PRIMARY KEY
	user_id	INTEGER	REFERENCES users(user_id) ON DELETE CASCADE
	name	VARCHAR(100)	NOT NULL
	rotator_one	VARCHAR(50)	NOT NULL
	rotator_two	VARCHAR(50)	NOT NULL
	rotator_three	VARCHAR(50)	NOT NULL
	rotator_one_ring_setting	INTEGER	NOT NULL
	rotator_two_ring_setting	INTEGER	NOT NULL
	rotator_three_ring_setting	INTEGER	NOT NULL
	rotator_one_ring_pos	INTEGER	NOT NULL
	rotator_two_ring_pos	INTEGER	NOT NULL
	rotator_three_ring_pos	INTEGER	NOT NULL
	reflector	VARCHAR(50)	NOT NULL
	plugboard	VARCHAR(255)	(nullable)
messages	message_id	SERIAL	PRIMARY KEY
	user_id	INTEGER	REFERENCES users(user_id) ON DELETE CASCADE
	config_id	INTEGER	REFERENCES configs(config_id) ON DELETE CASCADE
	message_text	TEXT	NOT NULL

4. Install NodeJS dependencies in both .../server and .../client folders

npm i

5. Run the backend server in .../server with this command hosted on port 8000

node server.js

6. Run the frontend server in .../client with this command hosted on port 3000.

npm start

7. Access locally hosted site at http://localhost:3000

References

Enigma Machine References

Below are resources used to make an accurate enigma machine emulator

• Based off of an enigma machine emulator for testing
• Enigma machine documentation
• Video explaining pieces of the enigma machine and how they worked
• Wiring diagrams for accurate to the original enigma machine Technical details of the enigma machine
• Based off of Aiden Seay's python implementation created for this project

Programming References

• MDN Web Docs for general web dev documentation
• React Simple Keyboard used for user input
• useState documentation
• useRef documentation
• useEffect documentation
• Supabase used as PostgreSQL server
• Supabase general pgAdmin documentation

Backend Technologies

• Express.js - Web application framework for Node.js
• PostgreSQL (pg) - PostgreSQL client for Node.js
• bcrypt - Password hashing library
• dotenv - Environment variable loader
• body-parser - Request body parsing middleware
• Comprehensive input validation - Server-side validation for all user inputs
• Global error handling - Centralized error management with proper HTTP status codes
• Database transaction management - ACID-compliant operations for data integrity
• Referential integrity enforcement - Proper deletion order prevents orphaned data

Frontend Technologies

• Axios - HTTP client for making API requests
• React Testing Library - Testing utilities for React
• Web Vitals - Performance monitoring library
• ESLint - Code linting and formatting
• React Scripts - Build tools and development server
• Client-side validation - Real-time input validation for better user experience
• Keyboard event handling - Physical keyboard support with shortcuts
• Responsive error handling - User-friendly error messages and loading states
• Enhanced user feedback - Specific error messages for different failure scenarios
• Data integrity warnings - Users are warned about cascading deletions

Historical Context

• Bletchley Park - Historical site where Enigma was broken
• Alan Turing - Mathematician who led the effort to break Enigma