Mercurial > public > enigma

annotate README.txt @ 45:19d33ff901af

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add more read the docs links in README. Adjust MANIFEST.in for docs.
author Brian Neal <bgneal@gmail.com>
date Tue, 05 Jun 2012 18:18:28 -0500
parents f2399d731ee1
children ad9d606ef5fa
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 Installation
bgneal@21 98 ------------
bgneal@21 99
bgneal@21 100 After the project gets a bit more mature I will add Py-Enigma to the `Python
bgneal@21 101 Package Index`_ (PyPI). In the meantime, you may download a tarball or .zip file
bgneal@21 102 of the latest code using the "get source" link on the `Py-Enigma Bitbucket
bgneal@21 103 page`_. Alternatively if you use Mercurial_, you can clone the repository with
bgneal@21 104 the following command::
bgneal@21 105
bgneal@21 106 $ hg clone https://bitbucket.org/bgneal/enigma
bgneal@21 107
bgneal@30 108 Once you have obtained a copy of the source somehow, to install::
bgneal@30 109
bgneal@30 110 $ python setup.py install
bgneal@21 111
bgneal@31 112
bgneal@21 113 Documentation
bgneal@21 114 -------------
bgneal@21 115
bgneal@45 116 The latest documentation is available at `Read the Docs
bgneal@45 117 <http://readthedocs.org/projects/py-enigma/>`_. There you can `browse the
bgneal@45 118 documentation online <http://readthedocs.org/docs/py-enigma/en/latest/>`_, or
bgneal@45 119 `download it in a variety of formats
bgneal@45 120 <http://readthedocs.org/projects/py-enigma/downloads/>`_.
bgneal@42 121
bgneal@42 122 Sources for the documentation are also included in Sphinx_ format. If you
bgneal@42 123 install Sphinx you can generate the documentation in several output formats.
bgneal@21 124
bgneal@31 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