Mercurial > public > purple

comparison README.txt @ 30:a58f91ead4ba v0.1.0

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Created setup.py and MANIFEST for distribution. Created purple script. Renamed README.rst to README.txt since distutils seemed to want either README or README.txt.
author Brian Neal <bgneal@gmail.com>
date Wed, 19 Feb 2014 18:58:34 -0600
parents README.rst@b90f0c599db7
children
comparison
equal deleted inserted replaced
29:b90f0c599db7 30:a58f91ead4ba
1 ======
2 Purple
3 ======
4
5 A historically accurate PURPLE simulator written in Python 3
6 ------------------------------------------------------------
7
8 :Author: Brian Neal <bgneal@gmail.com>
9 :Version: 0.1
10 :Date: February 17, 2013
11 :Home Page: https://bitbucket.org/bgneal/purple/
12 :License: MIT License (see LICENSE.txt)
13 :Documentation: This file
14 :Support: https://bitbucket.org/bgneal/purple/issues
15
16 ``Purple`` is a Python library and command-line utility for simulating the
17 `PURPLE Machine`_, a cipher machine used by the Japanese Foreign Office before
18 and during the Second World War. PURPLE was the code name given to the machine
19 by U.S. cryptanalysts. The Japanese called the machine *97-shiki ōbun inji-ki*
20 (System 97 Printing Machine for European Characters), and *Angōki B-kata* (Type
21 B Cipher Machine). The machine was used for secure diplomatic communications
22 and was implemented as an electromechanical stepping-switch device.
23
24 This project is a Python 3 library and command-line utility for encrypting and
25 decrypting text by simulating the operation of an actual PURPLE machine.
26
27 If you are brand new to the ``Purple`` cipher machine, please skip down to the
28 references section and familiarize yourself with the device. This will help you
29 understand the terminology used in the documentation, below.
30
31
32 Requirements
33 ############
34
35 ``Purple`` was written in Python_ 3, specifically 3.3.2, and has no other external
36 dependencies.
37
38
39 Installation
40 ############
41
42 ``Purple`` is available on the `Python Package Index`_ (PyPI). There are
43 a number of ways to install to ``Purple``, detailed below. The author
44 recommends you install into a virtualenv_. Setting up a virtualenv is not hard,
45 but describing it is out of scope for this document. Please see the virtualenv_
46 documentation for more information.
47
48 You can install it using pip_::
49
50 $ pip install purple # install
51 $ pip install --upgrade purple # upgrade
52
53 You can also visit the the `Purple Bitbucket page`_ and download an archive
54 file of the latest code. Alternatively, if you use Mercurial_, you can clone
55 the repository with the following command::
56
57 $ hg clone https://bitbucket.org/bgneal/purple
58
59 If you did not use pip_ (you downloaded or cloned the code yourself), you can
60 install with::
61
62 $ cd where-you-extracted-purple
63 $ python setup.py install
64
65 To run the unit tests::
66
67 $ cd where-you-extracted-purple
68 $ python -m unittest discover
69
70
71 Initial Settings Syntax
72 #######################
73
74 In order to exchange messages, each message recipient must use the same initial
75 machine settings. For the ``Purple`` machine, these settings are the initial
76 switch positions for the "sixes" and three "twenties" stepping switches, the
77 switch motion order (which twenties switch is the fast switch, which is the
78 middle switch, and which is the slow switch), and finally the plugboard
79 alphabet mapping.
80
81 The ``Purple`` simulation uses the following syntax in both its command-line
82 application and library code.
83
84 For the switches, we borrow the notation used by U.S. cryptanalysts, for
85 example::
86
87 9-1,24,6-23
88
89 Here the first number before leading dash, 9, indicates the starting position
90 of the sixes switch. The next three numbers are the starting positions for the
91 three twenties switches numbered 1, 2, and 3. Each switch position is a number
92 from 1 through 25, inclusive. Finally, after the last dash are two digits which
93 indicate the switch stepping motion. The first number, in this case 2,
94 indicates that the twenties switch #2 is the fast switch. The second number, 3,
95 indicates twenties switch #3 is the middle switch. Thus the slow switch, which
96 is never listed, is in this case twenties switch #1. When using this syntax, do
97 not insert space characters.
98
99 The plugboard alphabet setting describes how the input typewriters are wired to
100 the plugboard. We represent this setting as a string of the 26 uppercase
101 alphabet letters where the first six letters are the wiring to the sixes
102 switch, and the remaining 20 are wired to the first stage of the twenties
103 switches. For example::
104
105 AEIOUYBCDFGHJKLMNPQRSTVWXZ
106
107 For the alphabet setting to be valid, do not insert spaces, and ensure all 26
108 letters are used exactly once.
109
110
111 Command-line Usage
112 ##################
113
114 To get help on the command-line ``Purple`` utility, execute the ``purple``
115 command with the ``--help`` option::
116
117 $ purple --help
118 usage: purple [-h] [-e] [-d] [-f] [-s SWITCHES] [-a ALPHABET] [-t TEXT]
119 [-i FILE] [-g N] [-w N]
120
121 PURPLE cipher machine simulator
122
123 optional arguments:
124 -h, --help show this help message and exit
125 -e, --encrypt perform an encrypt operation
126 -d, --decrypt perform a decrypt operation
127 -f, --filter filter plaintext and provide useful substitutions
128 -s SWITCHES, --switches SWITCHES
129 switch settings, e.g. 9-1,24,6-23
130 -a ALPHABET, --alphabet ALPHABET
131 plugboard wiring string, 26-letters; e.g.
132 AEIOUYBCDFGHJKLMNPQRSTVWXZ
133 -t TEXT, --text TEXT input text to encrypt/decrypt
134 -i FILE, --input FILE
135 file to read input text from, - for stdin
136 -g N, --group N if non-zero, group output in N-letter groups [default:
137 5]
138 -w N, --width N wrap output text to N letters; a value of 0 means do
139 not wrap [default: 70]
140
141 Supply either -e or -d, but not both, to perform either an encrypt or decrypt.
142 If the -s option is not supplied, the value of the environment variable
143 PURPLE97_SWITCHES will be used. If the -a option is not supplied, the value of
144 the environment variable PURPLE97_ALPHABET will be used. Input text is
145 supplied either by the -t or by the -f options, but not both.
146
147 The ``purple`` command operates in two modes, either encrypt (specified with
148 ``-e`` or ``--encrypt``) or decrypt (``-d`` or ``--decrypt``). Input text can
149 be specified on the command-line with the ``-t`` or ``--text`` option, or
150 a read from a file (``-i`` or ``--input``).
151
152 The ``-s`` (or ``--switches``) and ``-a`` (or ``--alphabet``) settings
153 determine the initial machine settings. They use the syntax described above in
154 the Initial Settings Syntax section.
155
156 If you are going to be working with the same initial switch settings and
157 plugboard alphabet over many command invocations it may be more convenient to
158 specify them as environment variables instead of repeatedly using the
159 command-line arguments. The examples below assume these statements have been
160 executed::
161
162 $ export PURPLE97_SWITCHES=9-1,24,6-23
163 $ export PURPLE97_ALPHABET=NOKTYUXEQLHBRMPDICJASVWGZF
164
165 If you do not specify initial settings, the ``purple`` machine will attempt to
166 read them from these two environment variables. Failing that, ``purple`` will
167 use the following initial settings:
168
169 * default switch settings: 1-1,1,1-12
170 * default alphabet: AEIOUYBCDFGHJKLMNPQRSTVWXZ
171
172 When encrypting text, the ``purple`` machine only accepts the letters A-Z, but
173 also allows for "garble" letters to be indicated by using the ``-`` (dash)
174 character. This means all punctuation and spaces must be either be omitted or
175 input via some other convention. The ``-f`` or ``--filter`` flag, when present,
176 relaxes these restrictions a bit. When this flag is on, all lowercase letters
177 will be converted to uppercase, digits will be converted to words (e.g.
178 5 becomes FIVE), and all other characters will be ignored.
179
180 A simple encrypt example using the ``-f`` flag is given below::
181
182 $ purple --encrypt -t "The PURPLE machine is now online" -f
183 OGIVT SIAAH MWMHT VIBYY JUOJF UE
184
185 By default ``purple`` prints the output in 5-letter groups. This can be
186 disabled or customized with the ``--group`` and ``--width`` options.
187
188 To decrypt this message::
189
190 $ purple --decrypt -t "OGIVT SIAAH MWMHT VIBYY JUOJF UE"
191 THEPU RPLEM ACHIN EISNO WONLI NE
192
193 Note that spaces are ignored on input. Again the output is produced in 5-letter
194 groups and wrapped at 70 letters per line. Here is the output again with
195 grouping disabled::
196
197 $ purple -d -t "OGIVT SIAAH MWMHT VIBYY JUOJF UE" -g 0
198 THEPURPLEMACHINEISNOWONLINE
199
200 You can use file redirection to capture output in a file::
201
202 $ purple -e -t "The PURPLE machine is now online" -f > secret.txt
203 $ purple -d -i secret.txt
204 THEPU RPLEM ACHIN EISNO WONLI NE
205
206
207 Library Usage
208 #############
209
210 To use ``Purple`` from within Python code you must first construct
211 a ``Purple97`` object, which represents a single PURPLE cipher machine. The
212 constructor is given below::
213
214 class Purple97(switches_pos=None, fast_switch=1, middle_switch=2,
215 alphabet=None)
216
217 The ``switches_pos`` argument, when not ``None``, must be a 4-tuple or list of
218 4 integers that describe the initial switch positions. Element 0 is the sixes
219 initial position, and the remaining elements are the initial positions of the
220 three twenties switches. These values must be in the range 0-24, inclusive.
221 If ``None`` then switch positions of all zeroes is assumed.
222
223 The ``fast_switch`` argument indicates which twenties switch (numbered 1-3) is
224 the fast switch. Likewise, ``middle_switch`` indicates which switch is the
225 middle switch. The slow switch is inferred. It is an error to give the
226 ``fast_switch`` and ``middle_switch`` arguments the same value.
227
228 The ``alphabet`` argument is the plugboard alphabet mapping. It is expected to
229 be a 26-letter uppercase string. If ``None``, a mapping of
230 ``AEIOUYBCDFGHJKLMNPQRSTVWXZ`` is assumed.
231
232 For convenience, another constructor is provided that allows you to specify
233 initial settings in the syntax described above::
234
235 classmethod Purple97.from_key_sheet(switches, alphabet=None)
236
237 Here ``switches`` is a string in the syntax described above, e.g.
238 ``'9-1,24,6-23'``.
239
240 The ``alphabet`` argument is as described in the first constructor.
241
242 Once constructed, you can use the ``Purple97`` object to perform encrypt and
243 decrypt operations. For example::
244
245 from purple.machine import Purple97
246
247 purple = Purple97.from_key_sheet(
248 switches='9-1,24,6-23',
249 alphabet='NOKTYUXEQLHBRMPDICJASVWGZF')
250
251 ciphertext = purple.encrypt('THEPURPLEMACHINEISONLINE')
252
253 purple = Purple97([8, 0, 23, 5], fast_switch=2, middle_switch=3,
254 alphabet='NOKTYUXEQLHBRMPDICJASVWGZF')
255
256 plaintext = purple.decrypt(ciphertext)
257
258 For more information, please review the docstrings in the code.
259
260
261 Support
262 #######
263
264 To report a bug or suggest a feature, please use the issue tracker at the
265 `Purple Bitbucket page`_. You can also email the author using the address at
266 the top of this file.
267
268
269 References
270 ##########
271
272 #. *PURPLE Revealed: Simulation and Computer-aided Cryptanalysis of Angooki
273 Taipu B*, by Wes Freeman, Geoff Sullivan, and Frode Weierud. This paper
274 was published in Cryptologia, Volume 27, Issue 1, January, 2003, pp. 1-43.
275 #. Frode Weierud's CryptoCellar page: `The PURPLE Machine`_
276 #. Wikipedia Article: `PURPLE Machine`_
277
278 The paper in reference 1 is also available here:
279 http://cryptocellar.web.cern.ch/cryptocellar/pubs/PurpleRevealed.pdf
280
281 This simulator would not have been possible without Frode Weierud's
282 CryptoCellar page and the detailed explanations and analysis found in reference
283 1. The author is also deeply grateful for email discussions with Frode Weierud
284 and Geoff Sullivan who provided me with plaintext, advice, and encouragement.
285
286 The ``Purple`` simulator's operation was checked against the simulator found in
287 reference 2.
288
289
290 .. _PURPLE Machine: http://en.wikipedia.org/wiki/Purple_(cipher_machine)
291 .. _Python: http://www.python.org
292 .. _Python Package Index: http://pypi.python.org/pypi/purple/
293 .. _virtualenv: http://www.virtualenv.org/
294 .. _pip: http://www.pip-installer.org
295 .. _Purple Bitbucket page: https://bitbucket.org/bgneal/purple/
296 .. _Mercurial: http://mercurial.selenic.com/
297 .. _The PURPLE Machine: http://cryptocellar.web.cern.ch/cryptocellar/simula/purple/