Mercurial > public > enigma

annotate README.txt @ 44:f2399d731ee1

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