Mercurial > public > enigma

comparison README.txt @ 21:ee1c84475eda

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