Enigma Python library

About

Welcome to enigmapython, a Python package designed to emulate the legendary Enigma cryptographic machine used during World War II. enigmapython provides a faithful implementation of the Enigma machine, allowing users to explore and understand the workings of this historic device.

This project is listed on Wikipedia as a globally recognized Enigma machine simulator, noted for its historical accuracy.

Key Features

• Flexible Configuration: enigmapython allows customization of the Enigma machine configuration, enabling users to experiment with different rotor settings, reflectors, and ring positions.
• Easy Extension: enigmapython is designed to be easily extensible, allowing developers to add new features or enhance the existing implementation.
• Simple yet faithful: don't be fooled by its simplicity; enigmapython implements 100% the algorithms of many Enigma machine models, allowing to decode a message that has been encoded by a real Enigma machine and also the contrary.

Enigma mechanics

For a detailed description of the rotor movement and stepping logic, including pseudocode, please refer to the Enigma Mechanics documentation.

Historical Accuracy & Verification

enigmapython is rigorously tested against authentic historical data to ensure maximum accuracy.

• Authentic German Army Test Message from 1930: Documented by Frode Weierud's CryptoCellar, this test validates that the Enigma I implementation correctly handles the complex interaction of rotors, ring settings, and plugboard connections exactly as the original machines did. See the corresponding unit test for details.
• Authentic U-534 M4 Message P1030700: A message from the U-534 submarine (May 1945), validating the Enigma M4 implementation (including the Greek rotor and thin reflector) against historical intercepts. See the corresponding unit test for details.
• Enigma T (Tirpitz) Transcript & "Finnery" Procedure Tests: Validates the Enigma T machine implementation against authentic WWII joint German-Japanese naval intercepts and procedures documented on Frode Weierud's CryptoCellar.
  • "Finnery" Procedure: Simulates the historical wartime transmission procedure where operators manually advanced the settable reflector (ReflectorUKW_EnigmaT) one step in the alphabet after processing each 5-letter group.
  • Intercept Transcripts: Includes the authentic wartime ciphertexts of Message A (DAN C" C", 1814/6/27) and Message B (DAN C" C", 1947/6/28) transmitted on 6 March 1944 to the Japanese submarine Gimmatzu, providing a verified template for testing decryption against real intercepts. See the corresponding transcript unit tests for details.

Machines implementations

The following Enigma machine models (along with their rotors, reflectors and plugboards) have been implemented:

Enigma B (Sweden, s/n: A-133)*

*given the rarity of this model and the little documentation/simulators available, although I expect an encryption consistency on par with newer models, I was unable to test it as I would have liked

Enigma K (Commercial Enigma)

Enigma K Swiss

Enigma D (Commercial Enigma)

*Enigma D rotor turnover happens at Z when ringstellung is 0 (A), otherwise turnover position is calculated using the formula turnover = (ringstellung + 1) % 26.

Enigma Z (Z30 Mark I)*

Compared to the other machine models, this one encrypts numbers instead of letters.

*given the rarity of this model and the little documentation/simulators available, although I expect an encryption consistency on par with newer models, I was unable to test it as I would have liked

Enigma I

Enigma I Norway (Norenigma)

Enigma I Sondermaschine (special machine)

Enigma M3

Enigma M4

Enigma T (Tirpitz)

Custom Machine

You can create a fully customized Enigma machine by instantiating the base components manually. This allows you to define custom alphabets, wirings, and turnover positions.

from enigmapython.Enigma import Enigma
from enigmapython.Rotor import Rotor
from enigmapython.Reflector import Reflector
from enigmapython.SwappablePlugboard import SwappablePlugboard
from enigmapython.Etw import Etw
from enigmapython.Alphabets import Alphabets

# 1. Define alphabet
alphabet = Alphabets.lookup.get("latin_i18n_26chars_lowercase")

# 2. Create custom rotors
# Parameters: wiring, turnover_indexes, alphabet, initial_position, ring_setting
rotor1 = Rotor("ekmflgdqvzntowyhxuspaibrcj", [16], alphabet, 0, 0) # Turnover at 'q'
rotor2 = Rotor("ajdksiruxblhwtmcqgznpyfvoe", [4], alphabet, 0, 0)  # Turnover at 'e'
rotor3 = Rotor("bdfhjlcprtxvznyeiwgakmusqo", [21], alphabet, 0, 0) # Turnover at 'v'

# 3. Create custom reflector
reflector = Reflector("yruhqsldpxngokmiebfzcwvjat", alphabet)

# 4. Create other components
# Swappable plugboard allows you to connect pairs of letters
plugboard = SwappablePlugboard(alphabet=alphabet)
plugboard.swap("a", "z") # Example: swap 'a' with 'z'

etw = Etw(alphabet, alphabet) # Passthrough ETW using alphabet as wiring

# 5. Assemble the Enigma machine
engine = Enigma(plugboard, [rotor1, rotor2, rotor3], reflector, etw, auto_increment_rotors=True, alphabet=alphabet)

# 6. Encrypt/Decrypt
cipher = engine.input_string("hello")
print(f"Ciphertext: {cipher}") # Outputs: mfnca

Prerequisites

• Python 3.11
• Clone this repo, checkout the desired branch/tag and install requirements (pip install -r requirements.txt) or directly from PyPI using pip install enigmapython

Getting started

Get started by installing the package from PyPI (pip install enigmapython) and exploring the examples in the examples folder.

Documentation

Full API documentation is available on ReadTheDocs.

For additional details, you can also refer to the local documentation, examples, and code comments.

Known implementations

Here's a list containing all the known Enigma simulators that use the enigmapython API.

• Enigma TUI. Enigma TUI is a Terminal User Interface for Enigma machines, allowing you to simulate different Enigma machine models from the terminal. It employs enigmapython as Enigma engine.

• MicroPython Enigma Python. MicroPython Enigma Python is a side project to bring Enigma Python library also on ambedded devices which runs MicroPython. It has been referenced on https://awesome-micropython.com/#historical, a curated list of the best MicroPython libraries, in the Cryptography/Historical section.

• Retrocampus BBS Enigma simulator. When connected to the BBS, type E to access an Enigma I cypher machine whose backend is based on enigmapython.

• Smallest Enigma M4 Emulator. Smallest Enigma M4 Emulator is a technical specification and world record attempt for the smallest Enigma M4 emulator, using enigmapython's MicroPython compatibility on microscopic embedded devices.

• Enigma Python MCP Server. Enigma Python MCP Server is a Model Context Protocol (MCP) server that exposes the enigmapython cryptographic engine as tools for AI assistants, allowing LLMs (such as Claude) to natively encrypt and decrypt messages as it was during WWII.

In the case you leveraged enigmapython API in a project, either public or not, drop me an email at denis.maggiorotto[at]gmail.com and I'll be happy to list you here.

Credits/references

• Early days experiments with Python and Enigma (where this repo comes from) can be found at: https://github.com/denismaggior8/enigma-cypher

• Rotors wirings have been taken from Crypto Museum at this link https://www.cryptomuseum.com/crypto/enigma/wiring.htm

• Thanks to

  • Piotte13 https://piotte13.github.io/enigma-cipher/
  • Cryptii https://cryptii.com
  • PyEnigma https://pypi.org/project/pyenigma/
  • 101 computing https://www.101computing.net/enigma-machine-emulator/
  • DenCode Enigma simulator https://dencode.com/cipher/enigma
  • Enigma simulation in Javascript/HTML by Daniel Palloks https://people.physik.hu-berlin.de/~palloks/js/enigma/index_en.html
  • Enigma B A133 simulation in Javascript/HTML by Daniel Palloks https://people.physik.hu-berlin.de/~palloks/js/enigma/enigma-a133_v261_en.html
  • Enigma Z simulation in Javascript/HTML by Daniel Palloks https://people.physik.hu-berlin.de/~palloks/js/enigma/enigma-z_v262b_en.html

  for having helped me testing the correctness of the generated ciphertexts

Support

Found it useful/funny/educational? Please consider to or