Mercurial > public > enigma

annotate README.txt @ 46:ad9d606ef5fa

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Updates for upload to PyPI.
author Brian Neal <bgneal@gmail.com>
date Tue, 05 Jun 2012 19:03:36 -0500
parents 19d33ff901af
children
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@46 9 :Date: June 5, 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@46 100 Py-Enigma is available on the `Python Package Index`_ (PyPI). You can install it
bgneal@46 101 using pip_::
bgneal@46 102
bgneal@46 103 $ pip install py-enigma # install
bgneal@46 104 $ pip install --upgrade py-enigma # upgrade
bgneal@46 105
bgneal@46 106 You may also download a tarball or .zip file of the latest code using the "get
bgneal@46 107 source" link on the `Py-Enigma Bitbucket page`_. Alternatively if you use
bgneal@46 108 Mercurial_, you can clone the repository with the following command::
bgneal@21 109
bgneal@21 110 $ hg clone https://bitbucket.org/bgneal/enigma
bgneal@21 111
bgneal@46 112 If you did not use pip, you can install with this command::
bgneal@30 113
bgneal@30 114 $ python setup.py install
bgneal@21 115
bgneal@31 116
bgneal@21 117 Documentation
bgneal@21 118 -------------
bgneal@21 119
bgneal@45 120 The latest documentation is available at `Read the Docs
bgneal@45 121 <http://readthedocs.org/projects/py-enigma/>`_. There you can `browse the
bgneal@45 122 documentation online <http://readthedocs.org/docs/py-enigma/en/latest/>`_, or
bgneal@45 123 `download it in a variety of formats
bgneal@45 124 <http://readthedocs.org/projects/py-enigma/downloads/>`_.
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@46 164 .. _Python Package Index: http://pypi.python.org/pypi/py-enigma/
bgneal@46 165 .. _pip: http://pip.openplans.org/
bgneal@21 166 .. _Py-Enigma Bitbucket page: https://bitbucket.org/bgneal/enigma
bgneal@21 167 .. _Mercurial: http://mercurial.selenic.com/
bgneal@21 168 .. _Sphinx: http://sphinx.pocoo.org/
bgneal@21 169 .. _issue tracker: https://bitbucket.org/bgneal/enigma/issues
bgneal@21 170 .. _Cipher Machines and Cryptology website: http://users.telenet.be/d.rijmenants/index.htm
bgneal@21 171 .. _Technical Details of the Enigma Machine: http://users.telenet.be/d.rijmenants/en/enigmatech.htm
bgneal@21 172 .. _Enigma simulator: http://users.telenet.be/d.rijmenants/en/enigmasim.htm
bgneal@21 173 .. _Enigma Museum: http://w1tp.com/enigma/
bgneal@21 174 .. _The Enigma and the Bombe: http://www.ellsbury.com/enigmabombe.htm
bgneal@21 175 .. _Nadia Baker & Enigma demo: http://youtu.be/HBHYAzuVeWc