Introducing Py-Enigma
#####################

:date: 2012-06-06 18:45
:tags: Python, Py-Enigma, Enigma
:slug: introducing-py-enigma
:author: Brian Neal
:summary: I got the Enigma machine bug bad! I wrote a simulator in Python.

Py-Enigma
---------

For some strange reason, I don't even remember why or how, I found myself
browsing the `Wikipedia page for the Enigma Machine
<http://en.wikipedia.org/wiki/Enigma_machine>`_. I quickly became fascinated and
started surfing around some more. I found several Enigma machine simulators,
some of them even online. It suddenly occured to me that it would be a fun
project to try and write my own in Python_. I wanted to challenge myself to see
if I could figure it all without help, so I vowed not to look at anyone else's
source code.

In order to write an Enigma simulator, you need a really good technical
explanation of how it worked, along with numerous details like how the rotors
were wired. Fortunately I very quickly found Dirk Rijmenants' incredible `Cipher
Machines and Cryptology website`_. In particular, his `Technical Details of the
Enigma Machine`_ page was exactly what I was looking for, a real gold mine of
information. 

I had a long Memorial Day weekend, so I spent many hours in front of the
computer, consuming every word of Dirk's explanations and trying to sort it all
out in my head. And so a very fun marathon hacking session began. In the end I
got it figured out, and you cannot believe how excited I was when I was able to
decode actual Enigma messages from World War II!

And so `Py-Enigma <https://bitbucket.org/bgneal/enigma>`_ was born! Py-Enigma is
a historically accurate simulation library for war-time Enigma machines, written
in Python 3. I also included a simple command-line application for doing
scripting or quick commad-line experiments.

Lessons learned
---------------

Since I didn't really know what I was doing at first, I wrote little classes for
each of the components and unit tested them. I'm really glad I did this because
not only did it find bugs, it also made me think harder about the problem and
made me realize I didn't understand everything. When you make a mistake in
cryptography, very often the answer you get is gibberish and there is no way to
tell how close you are to the right answer. This was almost the case here, and I
think I stumbled upon an Enigma weakness that the allied codebreakers must have
seen also. I had a bug in my rotor stepping algorithm, and I got the right
answer up until the point where the right rotor stepped the middle rotor, then
the output went all garbage. Once I noticed this, I was able to focus on the
stepping algorithm and find the bug. I'm sure the allied codebreakers must have
experienced the same thing when they were guessing what rotors were being used
for the message they were cracking.

I also decided to use this little project to really learn Sphinx_. I had dabbled
around in it before when I contributed some documentation patches to Django_. I
think writing the documentation took almost as long as my research and coding,
but with Sphinx at least it was fun! It is a very useful and powerful package. I
also checked out the awesome `readthedocs.org <http://readthedocs.org>`_ and
quickly got my documentation `hosted there
<http://py-enigma.readthedocs.org/>`_. What a fantastic service! Now whenever I
push changes to bitbucket my docs are automatically built on readthedocs!

This was also my second project that I put up on PyPI. I'm a little bit more
comfortable with the packaging process, but it is still a bit bewildering given
all the choices.

Conclusion
----------

I hope folks who are interested in history, cryptography, World War II, and
Python find Py-Enigma useful and fun! You can get the code from either the
`Py-Enigma Bitbucket page`_ or from PyPI_. And a big thank-you to Dirk
Rijmenants!  Without his hard work and detailed explanation, Py-Enigma would
have been considerably more difficult.

.. _Python: http://www.python.org
.. _Cipher Machines and Cryptology website: http://users.telenet.be/d.rijmenants/index.htm
.. _Technical Details of the Enigma Machine: http://users.telenet.be/d.rijmenants/en/enigmatech.htm
.. _Sphinx: http://sphinx.pocoo.org/
.. _Django: http://www.djangoproject.com/
.. _Py-Enigma Bitbucket page: https://bitbucket.org/bgneal/enigma
.. _PyPI: http://pypi.python.org/pypi/py-enigma/