Mercurial > public > purple

comparison README.rst @ 26:3a53d309bbb7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Finished the README.
author Brian Neal <bgneal@gmail.com>
date Tue, 18 Feb 2014 19:25:54 -0600
parents 39d0121a018d
children b90f0c599db7
comparison
equal deleted inserted replaced
25:39d0121a018d 26:3a53d309bbb7
11 :Home Page: https://bitbucket.org/bgneal/purple/ 11 :Home Page: https://bitbucket.org/bgneal/purple/
12 :License: MIT License (see LICENSE.txt) 12 :License: MIT License (see LICENSE.txt)
13 :Documentation: This file 13 :Documentation: This file
14 :Support: https://bitbucket.org/bgneal/purple/issues 14 :Support: https://bitbucket.org/bgneal/purple/issues
15 15
16 ``Purple`` is a Python library and command-line utility for simulating the `PURPLE 16 ``Purple`` is a Python library and command-line utility for simulating the
17 Machine`_, a cipher machine used by the Japanese Foreign Office before and 17 `PURPLE Machine`_, a cipher machine used by the Japanese Foreign Office before
18 during the Second World War. PURPLE was the code name given to machine by U.S. 18 and during the Second World War. PURPLE was the code name given to the machine
19 cryptanalysts. The Japanese called the machine 97-shiki ōbun inji-ki (System 97 19 by U.S. cryptanalysts. The Japanese called the machine *97-shiki ōbun inji-ki*
20 Printing Machine for European Characters), and Angōki B-kata (Type B Cipher 20 (System 97 Printing Machine for European Characters), and *Angōki B-kata* (Type
21 Machine). The machine was used for secure diplomatic communications and was an 21 B Cipher Machine). The machine was used for secure diplomatic communications
22 electromechanical stepping-switch device. 22 and was implemented as an electromechanical stepping-switch device.
23 23
24 This project is a Python 3 library and command-line utility for encrypting and 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. 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.
26 30
27 31
28 Requirements 32 Requirements
29 ############ 33 ############
30 34
60 64
61 To run the unit tests:: 65 To run the unit tests::
62 66
63 $ cd where-you-extracted-purple 67 $ cd where-you-extracted-purple
64 $ python -m unittest discover 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.
65 109
66 110
67 Command-line Usage 111 Command-line Usage
68 ################## 112 ##################
69 113
98 If the -s option is not supplied, the value of the environment variable 142 If the -s option is not supplied, the value of the environment variable
99 PURPLE97_SWITCHES will be used. If the -a option is not supplied, the value of 143 PURPLE97_SWITCHES will be used. If the -a option is not supplied, the value of
100 the environment variable PURPLE97_ALPHABET will be used. Input text is 144 the environment variable PURPLE97_ALPHABET will be used. Input text is
101 supplied either by the -t or by the -f options, but not both. 145 supplied either by the -t or by the -f options, but not both.
102 146
103 (TODO: Text goes here explaining the switches and alphabet settings)
104
105 If you are going to be working with the same initial switch settings and
106 plugboard alphabet it may be more convenient to specify them as environment
107 variables instead of repeatedly using the command-line arguments ``-s`` and
108 ``-a``. The examples below assume these statements have been executed::
109
110 $ export PURPLE97_SWITCHES=9-1,24,6-23
111 $ export PURPLE97_ALPHABET=NOKTYUXEQLHBRMPDICJASVWGZF
112
113 The ``purple`` command operates in two modes, either encrypt (specified with 147 The ``purple`` command operates in two modes, either encrypt (specified with
114 ``-e`` or ``--encrypt``) or decrypt (``-d`` or ``--decrypt``). Input text can 148 ``-e`` or ``--encrypt``) or decrypt (``-d`` or ``--decrypt``). Input text can
115 be specified on the command-line with the ``-t`` or ``--text`` option, or 149 be specified on the command-line with the ``-t`` or ``--text`` option, or
116 a read from a file (``-i`` or ``--input``). 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
117 171
118 When encrypting text, the ``purple`` machine only accepts the letters A-Z, but 172 When encrypting text, the ``purple`` machine only accepts the letters A-Z, but
119 also allows for "garble" letters to be indicated by using the ``-`` (dash) 173 also allows for "garble" letters to be indicated by using the ``-`` (dash)
120 character. This means all punctuation and spaces must be either be omitted or 174 character. This means all punctuation and spaces must be either be omitted or
121 input via some other convention. The ``-f`` or ``--filter`` flag, when present, 175 input via some other convention. The ``-f`` or ``--filter`` flag, when present,
123 will be converted to uppercase, digits will be converted to words (e.g. 177 will be converted to uppercase, digits will be converted to words (e.g.
124 5 becomes FIVE), and all other characters will be ignored. 178 5 becomes FIVE), and all other characters will be ignored.
125 179
126 A simple encrypt example using the ``-f`` flag is given below:: 180 A simple encrypt example using the ``-f`` flag is given below::
127 181
128 $ purple -e -t "The PURPLE machine is now online" -f 182 $ purple --encrypt -t "The PURPLE machine is now online" -f
129 OGIVT SIAAH MWMHT VIBYY JUOJF UE 183 OGIVT SIAAH MWMHT VIBYY JUOJF UE
130 184
131 By default ``purple`` prints the output in 5-letter groups. This can be 185 By default ``purple`` prints the output in 5-letter groups. This can be
132 disabled or customized with the ``--group`` and ``--width`` options. 186 disabled or customized with the ``--group`` and ``--width`` options.
133 187
134 To decrypt this message:: 188 To decrypt this message::
135 189
136 $ purple -d -t "OGIVT SIAAH MWMHT VIBYY JUOJF UE" 190 $ purple --decrypt -t "OGIVT SIAAH MWMHT VIBYY JUOJF UE"
137 THEPU RPLEM ACHIN EISNO WONLI NE 191 THEPU RPLEM ACHIN EISNO WONLI NE
138 192
139 Note that spaces are ignored on input. Again the output is produced in 5-letter 193 Note that spaces are ignored on input. Again the output is produced in 5-letter
140 groups and wrapped at 70 letters per line. Here is the output again with 194 groups and wrapped at 70 letters per line. Here is the output again with
141 grouping disabled:: 195 grouping disabled::
142 196
143 $ purple -d -t "OGIVT SIAAH MWMHT VIBYY JUOJF UE" -g 0 197 $ purple -d -t "OGIVT SIAAH MWMHT VIBYY JUOJF UE" -g 0
144 THEPURPLEMACHINEISNOWONLINE 198 THEPURPLEMACHINEISNOWONLINE
145 199
146 Of course you can use file redirection to capture output in a file:: 200 You can use file redirection to capture output in a file::
147 201
148 $ purple -e -t "The PURPLE machine is now online" -f > secret.txt 202 $ purple -e -t "The PURPLE machine is now online" -f > secret.txt
149 $ purple -d -i secret.txt 203 $ purple -d -i secret.txt
150 THEPU RPLEM ACHIN EISNO WONLI NE 204 THEPU RPLEM ACHIN EISNO WONLI NE
151 205
152 206
153 Library Usage 207 Library Usage
154 ############# 208 #############
155 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
156 260
157 Support 261 Support
158 ####### 262 #######
159 263
264 To report a bug or suggest a feature, please use the issue tracker at the
265 `Purple Bitbucket page`_.
266
160 267
161 References 268 References
162 ########## 269 ##########
163 270
271 #. *PURPLE Revealed: Simulation and Computer-aided Cryptanalysis of Angooki
272 Taipu B*, by Wes Freeman, Geoff Sullivan, and Frode Weierud. This paper
273 was published in Cryptologia, Volume 27, Issue 1, January, 2003, pp. 1-43.
274 #. Frode Weierud's CryptoCellar page: `The PURPLE Machine`_
275 #. Wikipedia Article: `PURPLE Machine`_
276
277 The paper in reference 1 is also available here:
278 http://cryptocellar.web.cern.ch/cryptocellar/pubs/PurpleRevealed.pdf
279
280 This simulator would not have been possible without Frode Weierud's
281 CryptoCellar page and the detailed explanations and analysis found in reference
282 1. The author is also deeply grateful for email discussions with Frode Weierud
283 and Geoff Sullivan who provided me with plaintext, advice, and encouragement.
284
285 The ``Purple`` simulator's operation was checked against the simulator found in
286 reference 2.
287
164 288
165 .. _PURPLE Machine: http://en.wikipedia.org/wiki/Purple_(cipher_machine) 289 .. _PURPLE Machine: http://en.wikipedia.org/wiki/Purple_(cipher_machine)
166 .. _Python: http://www.python.org 290 .. _Python: http://www.python.org
167 .. _Python Package Index: http://pypi.python.org/pypi/m209/ 291 .. _Python Package Index: http://pypi.python.org/pypi/purple/
168 .. _virtualenv: http://www.virtualenv.org/ 292 .. _virtualenv: http://www.virtualenv.org/
169 .. _pip: http://www.pip-installer.org 293 .. _pip: http://www.pip-installer.org
170 .. _Purple Bitbucket page: https://bitbucket.org/bgneal/purple/ 294 .. _Purple Bitbucket page: https://bitbucket.org/bgneal/purple/
171 .. _Mercurial: http://mercurial.selenic.com/ 295 .. _Mercurial: http://mercurial.selenic.com/
296 .. _The PURPLE Machine: http://cryptocellar.web.cern.ch/cryptocellar/simula/purple/