Mercurial > public > enigma

annotate README.txt @ 41:3057f16caa43

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Documented the key file format.
author Brian Neal <bgneal@gmail.com>
date Mon, 04 Jun 2012 20:24:38 -0500
parents 560ded21dcd9
children 360534b4781d
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@30 8 :Version: Alpha
bgneal@30 9 :Date: May 30, 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@31 18 **Py-Enigma** is a Python 3 library for simulating the `Enigma machines`_ used
bgneal@31 19 by the German armed forces (Wehrmacht) during World War 2. Py-Enigma makes it
bgneal@31 20 possible to both encrypt and decrypt messages that can be sent to, or received
bgneal@31 21 from, 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@29 77 Py-Enigma also includes a command-line application for processing messages.
bgneal@29 78 Assuming you have a proper key file that contains the same initial settings as
bgneal@29 79 the code above, the above example can be performed on the command-line::
bgneal@29 80
bgneal@30 81 $ pyenigma.py --key-file=keys.txt --start=WXC --text='KCH'
bgneal@29 82 BLA
bgneal@30 83 $ pyenigma.py --key-file=keys.txt --start=BLA --text='NIBLFMYMLLUFWCASCSSNVHAZ'
bgneal@29 84 THEXRUSSIANSXAREXCOMINGX
bgneal@29 85
bgneal@29 86 The format of the key file can be found in the documentation.
bgneal@29 87
bgneal@21 88
bgneal@21 89 Requirements
bgneal@21 90 ------------
bgneal@21 91
bgneal@30 92 Py-Enigma is written in Python_, specifically Python 3.2. It has no other
bgneal@21 93 requirements or dependencies.
bgneal@21 94
bgneal@21 95
bgneal@21 96 Project Status
bgneal@21 97 --------------
bgneal@21 98
bgneal@21 99 This project is very new and is considered alpha software. However at even this
bgneal@21 100 stage it is possible to encrypt and decrypt authentic Enigma messages.
bgneal@21 101
bgneal@21 102
bgneal@21 103 Installation
bgneal@21 104 ------------
bgneal@21 105
bgneal@21 106 After the project gets a bit more mature I will add Py-Enigma to the `Python
bgneal@21 107 Package Index`_ (PyPI). In the meantime, you may download a tarball or .zip file
bgneal@21 108 of the latest code using the "get source" link on the `Py-Enigma Bitbucket
bgneal@21 109 page`_. Alternatively if you use Mercurial_, you can clone the repository with
bgneal@21 110 the following command::
bgneal@21 111
bgneal@21 112 $ hg clone https://bitbucket.org/bgneal/enigma
bgneal@21 113
bgneal@30 114 Once you have obtained a copy of the source somehow, to install::
bgneal@30 115
bgneal@30 116 $ python setup.py install
bgneal@21 117
bgneal@31 118
bgneal@21 119 Documentation
bgneal@21 120 -------------
bgneal@21 121
bgneal@21 122 I want to use Py-Enigma as a chance to learn Sphinx_, so you can expect to see
bgneal@21 123 some nicely formatted documentation coming soon. In the meantime, please read
bgneal@21 124 the source code. I commented it heavily so I could understand how the Enigma
bgneal@21 125 machine works.
bgneal@21 126
bgneal@31 127
bgneal@21 128 Support
bgneal@21 129 -------
bgneal@21 130
bgneal@21 131 Support is provided at the `issue tracker`_ at the `Py-Enigma Bitbucket page`_.
bgneal@21 132 If you have general questions or comments, please feel free to email me (address
bgneal@21 133 at the top of this file).
bgneal@21 134
bgneal@21 135 And please, if you use Py-Enigma for anything, even if it is just learning,
bgneal@21 136 please let me know!
bgneal@21 137
bgneal@21 138
bgneal@21 139 Acknowledgements & References
bgneal@21 140 -----------------------------
bgneal@21 141
bgneal@21 142 This software would not have been possible without the thorough and detailed
bgneal@21 143 descriptions of the Enigma machine on Dirk Rijmenants' incredible `Cipher
bgneal@21 144 Machines and Cryptology website`_. In particular, his `Technical Details of the
bgneal@21 145 Enigma Machine`_ page was a gold mine of information.
bgneal@21 146
bgneal@21 147 Dirk has also written an `Enigma simulator`_ in Visual Basic. Although I did not
bgneal@21 148 look at his source code, I did use his simulator to check the operation of
bgneal@21 149 Py-Enigma.
bgneal@21 150
bgneal@21 151 I would also like to recommend the photos and video at Dr. Thomas B. Perera's
bgneal@21 152 `Enigma Museum`_.
bgneal@21 153
bgneal@21 154 Another good website is `The Enigma and the Bombe`_ by Graham Ellsbury.
bgneal@21 155
bgneal@21 156 A nice video which shows the basic components and operation of the Enigma
bgneal@21 157 Machine is on YouTube: `Nadia Baker & Enigma demo`_.
bgneal@21 158
bgneal@21 159
bgneal@21 160 .. _Enigma machines: http://en.wikipedia.org/wiki/Enigma_machine
bgneal@21 161 .. _Python: http://www.python.org
bgneal@21 162 .. _Python Package Index: http://pypi.python.org/pypi
bgneal@21 163 .. _Py-Enigma Bitbucket page: https://bitbucket.org/bgneal/enigma
bgneal@21 164 .. _Mercurial: http://mercurial.selenic.com/
bgneal@21 165 .. _Sphinx: http://sphinx.pocoo.org/
bgneal@21 166 .. _issue tracker: https://bitbucket.org/bgneal/enigma/issues
bgneal@21 167 .. _Cipher Machines and Cryptology website: http://users.telenet.be/d.rijmenants/index.htm
bgneal@21 168 .. _Technical Details of the Enigma Machine: http://users.telenet.be/d.rijmenants/en/enigmatech.htm
bgneal@21 169 .. _Enigma simulator: http://users.telenet.be/d.rijmenants/en/enigmasim.htm
bgneal@21 170 .. _Enigma Museum: http://w1tp.com/enigma/
bgneal@21 171 .. _The Enigma and the Bombe: http://www.ellsbury.com/enigmabombe.htm
bgneal@21 172 .. _Nadia Baker & Enigma demo: http://youtu.be/HBHYAzuVeWc