bgneal@21: ========= bgneal@21: Py-Enigma bgneal@21: ========= bgneal@21: A historically accurate Enigma Machine library written in Python 3 bgneal@21: ------------------------------------------------------------------ bgneal@21: bgneal@21: :Author: Brian Neal bgneal@30: :Version: Alpha bgneal@30: :Date: May 30, 2012 bgneal@21: :Home Page: https://bitbucket.org/bgneal/enigma/ bgneal@21: :License: MIT License (see LICENSE.txt) bgneal@21: :Support: https://bitbucket.org/bgneal/enigma/issues bgneal@21: bgneal@21: bgneal@21: Overview bgneal@21: -------- bgneal@21: bgneal@21: **Py-Enigma** is a Python 3 library for simulating the `Enigma machines`_ used by bgneal@21: the German armed forces (Wehrmacht) during World War 2. Py-Enigma makes it bgneal@21: possible to both encrypt and decrypt messages that can be read by, or written bgneal@21: to, actual Enigma machines used by the German army (Heer), air force bgneal@21: (Luftwaffe), and navy (Kriegsmarine). bgneal@21: bgneal@21: It is my hope that library will be useful to Enigma enthusiasts, historians, and bgneal@21: students interested in cryptography. bgneal@21: bgneal@21: Py-Enigma strives to be Pythonic, easy to use, comes with unit tests, and bgneal@21: (coming soon) documentation. bgneal@21: bgneal@21: bgneal@21: Scope bgneal@21: ----- bgneal@21: bgneal@21: The current scope of Py-Enigma is to simulate Wehrmacht Enigma machines. bgneal@21: Simulation of other Enigmas, such as the various commercial, railroad, foreign, bgneal@21: and Abwher (Military Intelligence) models may come later if there is enough bgneal@21: interest and data available. bgneal@21: bgneal@21: Currently, Py-Enigma can simulate the 3 and 4 rotor Enigma machines used by the bgneal@21: German army, navy, and air force. bgneal@21: bgneal@21: bgneal@21: Quick Example bgneal@21: ------------- bgneal@21: bgneal@21: This example shows how the library can be used to decode a message using the bgneal@24: procedure employed by the German army:: bgneal@21: bgneal@21: from enigma.machine import EnigmaMachine bgneal@21: bgneal@21: # setup machine according to specs from a daily key sheet: bgneal@21: bgneal@21: machine = EnigmaMachine.from_key_sheet( bgneal@21: rotors='II IV V', bgneal@21: reflector='B', bgneal@21: ring_settings=[1, 20, 11], bgneal@21: plugboard_settings='AV BS CG DL FU HZ IN KM OW RX') bgneal@21: bgneal@21: # set machine initial starting position bgneal@21: machine.set_display('WXC') bgneal@21: bgneal@21: # decrypt the message key bgneal@21: msg_key = machine.process_text('KCH') bgneal@21: bgneal@21: # decrypt the cipher text with the unencrypted message key bgneal@21: machine.set_display(msg_key) bgneal@21: bgneal@21: ciphertext = 'NIBLFMYMLLUFWCASCSSNVHAZ' bgneal@21: plaintext = machine.process_text(ciphertext) bgneal@21: bgneal@21: print(plaintext) bgneal@21: bgneal@21: This program prints:: bgneal@21: bgneal@21: THEXRUSSIANSXAREXCOMINGX bgneal@21: bgneal@29: Py-Enigma also includes a command-line application for processing messages. bgneal@29: Assuming you have a proper key file that contains the same initial settings as bgneal@29: the code above, the above example can be performed on the command-line:: bgneal@29: bgneal@30: $ pyenigma.py --key-file=keys.txt --start=WXC --text='KCH' bgneal@29: BLA bgneal@30: $ pyenigma.py --key-file=keys.txt --start=BLA --text='NIBLFMYMLLUFWCASCSSNVHAZ' bgneal@29: THEXRUSSIANSXAREXCOMINGX bgneal@29: bgneal@29: The format of the key file can be found in the documentation. bgneal@29: bgneal@21: bgneal@21: Requirements bgneal@21: ------------ bgneal@21: bgneal@30: Py-Enigma is written in Python_, specifically Python 3.2. It has no other bgneal@21: requirements or dependencies. bgneal@21: bgneal@21: bgneal@21: Project Status bgneal@21: -------------- bgneal@21: bgneal@21: This project is very new and is considered alpha software. However at even this bgneal@21: stage it is possible to encrypt and decrypt authentic Enigma messages. bgneal@21: bgneal@21: bgneal@21: Installation bgneal@21: ------------ bgneal@21: bgneal@21: After the project gets a bit more mature I will add Py-Enigma to the `Python bgneal@21: Package Index`_ (PyPI). In the meantime, you may download a tarball or .zip file bgneal@21: of the latest code using the "get source" link on the `Py-Enigma Bitbucket bgneal@21: page`_. Alternatively if you use Mercurial_, you can clone the repository with bgneal@21: the following command:: bgneal@21: bgneal@21: $ hg clone https://bitbucket.org/bgneal/enigma bgneal@21: bgneal@30: Once you have obtained a copy of the source somehow, to install:: bgneal@30: bgneal@30: $ python setup.py install bgneal@21: bgneal@21: Documentation bgneal@21: ------------- bgneal@21: bgneal@21: I want to use Py-Enigma as a chance to learn Sphinx_, so you can expect to see bgneal@21: some nicely formatted documentation coming soon. In the meantime, please read bgneal@21: the source code. I commented it heavily so I could understand how the Enigma bgneal@21: machine works. bgneal@21: bgneal@21: Support bgneal@21: ------- bgneal@21: bgneal@21: Support is provided at the `issue tracker`_ at the `Py-Enigma Bitbucket page`_. bgneal@21: If you have general questions or comments, please feel free to email me (address bgneal@21: at the top of this file). bgneal@21: bgneal@21: And please, if you use Py-Enigma for anything, even if it is just learning, bgneal@21: please let me know! bgneal@21: bgneal@21: bgneal@21: Acknowledgements & References bgneal@21: ----------------------------- bgneal@21: bgneal@21: This software would not have been possible without the thorough and detailed bgneal@21: descriptions of the Enigma machine on Dirk Rijmenants' incredible `Cipher bgneal@21: Machines and Cryptology website`_. In particular, his `Technical Details of the bgneal@21: Enigma Machine`_ page was a gold mine of information. bgneal@21: bgneal@21: Dirk has also written an `Enigma simulator`_ in Visual Basic. Although I did not bgneal@21: look at his source code, I did use his simulator to check the operation of bgneal@21: Py-Enigma. bgneal@21: bgneal@21: I would also like to recommend the photos and video at Dr. Thomas B. Perera's bgneal@21: `Enigma Museum`_. bgneal@21: bgneal@21: Another good website is `The Enigma and the Bombe`_ by Graham Ellsbury. bgneal@21: bgneal@21: A nice video which shows the basic components and operation of the Enigma bgneal@21: Machine is on YouTube: `Nadia Baker & Enigma demo`_. bgneal@21: bgneal@21: bgneal@21: .. _Enigma machines: http://en.wikipedia.org/wiki/Enigma_machine bgneal@21: .. _Python: http://www.python.org bgneal@21: .. _Python Package Index: http://pypi.python.org/pypi bgneal@21: .. _Py-Enigma Bitbucket page: https://bitbucket.org/bgneal/enigma bgneal@21: .. _Mercurial: http://mercurial.selenic.com/ bgneal@21: .. _Sphinx: http://sphinx.pocoo.org/ bgneal@21: .. _issue tracker: https://bitbucket.org/bgneal/enigma/issues bgneal@21: .. _Cipher Machines and Cryptology website: http://users.telenet.be/d.rijmenants/index.htm bgneal@21: .. _Technical Details of the Enigma Machine: http://users.telenet.be/d.rijmenants/en/enigmatech.htm bgneal@21: .. _Enigma simulator: http://users.telenet.be/d.rijmenants/en/enigmasim.htm bgneal@21: .. _Enigma Museum: http://w1tp.com/enigma/ bgneal@21: .. _The Enigma and the Bombe: http://www.ellsbury.com/enigmabombe.htm bgneal@21: .. _Nadia Baker & Enigma demo: http://youtu.be/HBHYAzuVeWc