Mercurial > public > enigma

annotate README.txt @ 29:f8734f73baa8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Update the README with an example command-line invocation.
author Brian Neal <bgneal@gmail.com>
date Tue, 29 May 2012 17:30:49 -0500
parents 9e499e386fac
children 62e0d0e2628b
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@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@29 81 $ pyenigma --key-file=keys.txt --start=WXC --text='KCH'
bgneal@29 82 BLA
bgneal@29 83 $ pyenigma --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@21 92 Py-Enigma is written in Python_, specifically Python 3. 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@21 114 In the very near future I will provide a ``setup.py`` script that will allow you
bgneal@21 115 to install Py-Enigma. For the time being, just place the ``enigma`` directory on
bgneal@21 116 your ``PYTHONPATH``.
bgneal@21 117
bgneal@21 118 Documentation
bgneal@21 119 -------------
bgneal@21 120
bgneal@21 121 I want to use Py-Enigma as a chance to learn Sphinx_, so you can expect to see
bgneal@21 122 some nicely formatted documentation coming soon. In the meantime, please read
bgneal@21 123 the source code. I commented it heavily so I could understand how the Enigma
bgneal@21 124 machine works.
bgneal@21 125
bgneal@21 126 Support
bgneal@21 127 -------
bgneal@21 128
bgneal@21 129 Support is provided at the `issue tracker`_ at the `Py-Enigma Bitbucket page`_.
bgneal@21 130 If you have general questions or comments, please feel free to email me (address
bgneal@21 131 at the top of this file).
bgneal@21 132
bgneal@21 133 And please, if you use Py-Enigma for anything, even if it is just learning,
bgneal@21 134 please let me know!
bgneal@21 135
bgneal@21 136
bgneal@21 137 Acknowledgements & References
bgneal@21 138 -----------------------------
bgneal@21 139
bgneal@21 140 This software would not have been possible without the thorough and detailed
bgneal@21 141 descriptions of the Enigma machine on Dirk Rijmenants' incredible `Cipher
bgneal@21 142 Machines and Cryptology website`_. In particular, his `Technical Details of the
bgneal@21 143 Enigma Machine`_ page was a gold mine of information.
bgneal@21 144
bgneal@21 145 Dirk has also written an `Enigma simulator`_ in Visual Basic. Although I did not
bgneal@21 146 look at his source code, I did use his simulator to check the operation of
bgneal@21 147 Py-Enigma.
bgneal@21 148
bgneal@21 149 I would also like to recommend the photos and video at Dr. Thomas B. Perera's
bgneal@21 150 `Enigma Museum`_.
bgneal@21 151
bgneal@21 152 Another good website is `The Enigma and the Bombe`_ by Graham Ellsbury.
bgneal@21 153
bgneal@21 154 A nice video which shows the basic components and operation of the Enigma
bgneal@21 155 Machine is on YouTube: `Nadia Baker & Enigma demo`_.
bgneal@21 156
bgneal@21 157
bgneal@21 158 .. _Enigma machines: http://en.wikipedia.org/wiki/Enigma_machine
bgneal@21 159 .. _Python: http://www.python.org
bgneal@21 160 .. _Python Package Index: http://pypi.python.org/pypi
bgneal@21 161 .. _Py-Enigma Bitbucket page: https://bitbucket.org/bgneal/enigma
bgneal@21 162 .. _Mercurial: http://mercurial.selenic.com/
bgneal@21 163 .. _Sphinx: http://sphinx.pocoo.org/
bgneal@21 164 .. _issue tracker: https://bitbucket.org/bgneal/enigma/issues
bgneal@21 165 .. _Cipher Machines and Cryptology website: http://users.telenet.be/d.rijmenants/index.htm
bgneal@21 166 .. _Technical Details of the Enigma Machine: http://users.telenet.be/d.rijmenants/en/enigmatech.htm
bgneal@21 167 .. _Enigma simulator: http://users.telenet.be/d.rijmenants/en/enigmasim.htm
bgneal@21 168 .. _Enigma Museum: http://w1tp.com/enigma/
bgneal@21 169 .. _The Enigma and the Bombe: http://www.ellsbury.com/enigmabombe.htm
bgneal@21 170 .. _Nadia Baker & Enigma demo: http://youtu.be/HBHYAzuVeWc