Mercurial > public > enigma

annotate README.txt @ 27:dc7f939a2ebf

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
First cut at a command-line app to encrypt/decrypt.
author Brian Neal <bgneal@gmail.com>
date Tue, 29 May 2012 17:12:42 -0500
parents 9e499e386fac
children f8734f73baa8
rev   line source
bgneal@21 1 =========
bgneal@21 2 Py-Enigma
bgneal@21 3 =========
bgneal@21 4 A historically accurate Enigma Machine library written in Python 3
bgneal@21 5 ------------------------------------------------------------------
bgneal@21 6
bgneal@21 7 :Author: Brian Neal <bgneal@gmail.com>
bgneal@21 8 :Version: 0.1
bgneal@21 9 :Date: May 28, 2012
bgneal@21 10 :Home Page: https://bitbucket.org/bgneal/enigma/
bgneal@21 11 :License: MIT License (see LICENSE.txt)
bgneal@21 12 :Support: https://bitbucket.org/bgneal/enigma/issues
bgneal@21 13
bgneal@21 14
bgneal@21 15 Overview
bgneal@21 16 --------
bgneal@21 17
bgneal@21 18 **Py-Enigma** is a Python 3 library for simulating the `Enigma machines`_ used by
bgneal@21 19 the German armed forces (Wehrmacht) during World War 2. Py-Enigma makes it
bgneal@21 20 possible to both encrypt and decrypt messages that can be read by, or written
bgneal@21 21 to, actual Enigma machines used by the German army (Heer), air force
bgneal@21 22 (Luftwaffe), and navy (Kriegsmarine).
bgneal@21 23
bgneal@21 24 It is my hope that library will be useful to Enigma enthusiasts, historians, and
bgneal@21 25 students interested in cryptography.
bgneal@21 26
bgneal@21 27 Py-Enigma strives to be Pythonic, easy to use, comes with unit tests, and
bgneal@21 28 (coming soon) documentation.
bgneal@21 29
bgneal@21 30
bgneal@21 31 Scope
bgneal@21 32 -----
bgneal@21 33
bgneal@21 34 The current scope of Py-Enigma is to simulate Wehrmacht Enigma machines.
bgneal@21 35 Simulation of other Enigmas, such as the various commercial, railroad, foreign,
bgneal@21 36 and Abwher (Military Intelligence) models may come later if there is enough
bgneal@21 37 interest and data available.
bgneal@21 38
bgneal@21 39 Currently, Py-Enigma can simulate the 3 and 4 rotor Enigma machines used by the
bgneal@21 40 German army, navy, and air force.
bgneal@21 41
bgneal@21 42
bgneal@21 43 Quick Example
bgneal@21 44 -------------
bgneal@21 45
bgneal@21 46 This example shows how the library can be used to decode a message using the
bgneal@24 47 procedure employed by the German army::
bgneal@21 48
bgneal@21 49 from enigma.machine import EnigmaMachine
bgneal@21 50
bgneal@21 51 # setup machine according to specs from a daily key sheet:
bgneal@21 52
bgneal@21 53 machine = EnigmaMachine.from_key_sheet(
bgneal@21 54 rotors='II IV V',
bgneal@21 55 reflector='B',
bgneal@21 56 ring_settings=[1, 20, 11],
bgneal@21 57 plugboard_settings='AV BS CG DL FU HZ IN KM OW RX')
bgneal@21 58
bgneal@21 59 # set machine initial starting position
bgneal@21 60 machine.set_display('WXC')
bgneal@21 61
bgneal@21 62 # decrypt the message key
bgneal@21 63 msg_key = machine.process_text('KCH')
bgneal@21 64
bgneal@21 65 # decrypt the cipher text with the unencrypted message key
bgneal@21 66 machine.set_display(msg_key)
bgneal@21 67
bgneal@21 68 ciphertext = 'NIBLFMYMLLUFWCASCSSNVHAZ'
bgneal@21 69 plaintext = machine.process_text(ciphertext)
bgneal@21 70
bgneal@21 71 print(plaintext)
bgneal@21 72
bgneal@21 73 This program prints::
bgneal@21 74
bgneal@21 75 THEXRUSSIANSXAREXCOMINGX
bgneal@21 76
bgneal@21 77
bgneal@21 78 Requirements
bgneal@21 79 ------------
bgneal@21 80
bgneal@21 81 Py-Enigma is written in Python_, specifically Python 3. It has no other
bgneal@21 82 requirements or dependencies.
bgneal@21 83
bgneal@21 84
bgneal@21 85 Project Status
bgneal@21 86 --------------
bgneal@21 87
bgneal@21 88 This project is very new and is considered alpha software. However at even this
bgneal@21 89 stage it is possible to encrypt and decrypt authentic Enigma messages.
bgneal@21 90
bgneal@21 91
bgneal@21 92 Installation
bgneal@21 93 ------------
bgneal@21 94
bgneal@21 95 After the project gets a bit more mature I will add Py-Enigma to the `Python
bgneal@21 96 Package Index`_ (PyPI). In the meantime, you may download a tarball or .zip file
bgneal@21 97 of the latest code using the "get source" link on the `Py-Enigma Bitbucket
bgneal@21 98 page`_. Alternatively if you use Mercurial_, you can clone the repository with
bgneal@21 99 the following command::
bgneal@21 100
bgneal@21 101 $ hg clone https://bitbucket.org/bgneal/enigma
bgneal@21 102
bgneal@21 103 In the very near future I will provide a ``setup.py`` script that will allow you
bgneal@21 104 to install Py-Enigma. For the time being, just place the ``enigma`` directory on
bgneal@21 105 your ``PYTHONPATH``.
bgneal@21 106
bgneal@21 107 Documentation
bgneal@21 108 -------------
bgneal@21 109
bgneal@21 110 I want to use Py-Enigma as a chance to learn Sphinx_, so you can expect to see
bgneal@21 111 some nicely formatted documentation coming soon. In the meantime, please read
bgneal@21 112 the source code. I commented it heavily so I could understand how the Enigma
bgneal@21 113 machine works.
bgneal@21 114
bgneal@21 115 Support
bgneal@21 116 -------
bgneal@21 117
bgneal@21 118 Support is provided at the `issue tracker`_ at the `Py-Enigma Bitbucket page`_.
bgneal@21 119 If you have general questions or comments, please feel free to email me (address
bgneal@21 120 at the top of this file).
bgneal@21 121
bgneal@21 122 And please, if you use Py-Enigma for anything, even if it is just learning,
bgneal@21 123 please let me know!
bgneal@21 124
bgneal@21 125
bgneal@21 126 Acknowledgements & References
bgneal@21 127 -----------------------------
bgneal@21 128
bgneal@21 129 This software would not have been possible without the thorough and detailed
bgneal@21 130 descriptions of the Enigma machine on Dirk Rijmenants' incredible `Cipher
bgneal@21 131 Machines and Cryptology website`_. In particular, his `Technical Details of the
bgneal@21 132 Enigma Machine`_ page was a gold mine of information.
bgneal@21 133
bgneal@21 134 Dirk has also written an `Enigma simulator`_ in Visual Basic. Although I did not
bgneal@21 135 look at his source code, I did use his simulator to check the operation of
bgneal@21 136 Py-Enigma.
bgneal@21 137
bgneal@21 138 I would also like to recommend the photos and video at Dr. Thomas B. Perera's
bgneal@21 139 `Enigma Museum`_.
bgneal@21 140
bgneal@21 141 Another good website is `The Enigma and the Bombe`_ by Graham Ellsbury.
bgneal@21 142
bgneal@21 143 A nice video which shows the basic components and operation of the Enigma
bgneal@21 144 Machine is on YouTube: `Nadia Baker & Enigma demo`_.
bgneal@21 145
bgneal@21 146
bgneal@21 147 .. _Enigma machines: http://en.wikipedia.org/wiki/Enigma_machine
bgneal@21 148 .. _Python: http://www.python.org
bgneal@21 149 .. _Python Package Index: http://pypi.python.org/pypi
bgneal@21 150 .. _Py-Enigma Bitbucket page: https://bitbucket.org/bgneal/enigma
bgneal@21 151 .. _Mercurial: http://mercurial.selenic.com/
bgneal@21 152 .. _Sphinx: http://sphinx.pocoo.org/
bgneal@21 153 .. _issue tracker: https://bitbucket.org/bgneal/enigma/issues
bgneal@21 154 .. _Cipher Machines and Cryptology website: http://users.telenet.be/d.rijmenants/index.htm
bgneal@21 155 .. _Technical Details of the Enigma Machine: http://users.telenet.be/d.rijmenants/en/enigmatech.htm
bgneal@21 156 .. _Enigma simulator: http://users.telenet.be/d.rijmenants/en/enigmasim.htm
bgneal@21 157 .. _Enigma Museum: http://w1tp.com/enigma/
bgneal@21 158 .. _The Enigma and the Bombe: http://www.ellsbury.com/enigmabombe.htm
bgneal@21 159 .. _Nadia Baker & Enigma demo: http://youtu.be/HBHYAzuVeWc