Mercurial > public > enigma

annotate README.txt @ 42:360534b4781d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Updated README and docs with link to Read the Docs page.
author Brian Neal <bgneal@gmail.com>
date Mon, 04 Jun 2012 20:51:05 -0500
parents 560ded21dcd9
children f2399d731ee1
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@42 12 :Documentation: http://readthedocs.org/docs/py-enigma/en/latest/
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