Mercurial > public > m209

comparison docs/index.rst @ 54:7fd3ec5580ab

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
More work on the docs. Added command-line tutorial.
author Brian Neal <bgneal@gmail.com>
date Fri, 05 Jul 2013 14:18:52 -0500
parents 5b335e8af407
children 9341896b93f0
comparison
equal deleted inserted replaced
53:41df1e5308e9 54:7fd3ec5580ab
28 and documentation. ``m209`` is a library for building applications for 28 and documentation. ``m209`` is a library for building applications for
29 encrypting and decrypting M-209 messages. ``m209`` also ships with a simple 29 encrypting and decrypting M-209 messages. ``m209`` also ships with a simple
30 command-line application that can encrypt & decrypt messages for scripting and 30 command-line application that can encrypt & decrypt messages for scripting and
31 experimentation. 31 experimentation.
32 32
33 Command-line Example 33 Command-line Tutorial
34 -------------------- 34 ---------------------
35 35
36 Library Example 36 In order for two parties to exchange M-209 messages, each must set up their
37 --------------- 37 device in exactly the same manner. This was accomplished by publishing key
38 lists in code books which were distributed to end users. A code book instructed
39 users on what key list to use on any given day in a given month. Each key list
40 detailed the numerous wheel pin and lug settings that needed to be made for
41 a given day. Because there are so many settings, the ``m209`` utility allows
42 users to store key lists in a key file for convenience. So let us first create
43 a key file that hold 30 key lists::
44
45 $ m209 keygen -n 30
46
47 This command randomly creates 30 key lists and stores them in a file called
48 ``m209keys.cfg`` by default. We did not specify a starting key list indicator, so
49 30 random ones were chosen. The first 13 lines of our new key file are
50 displayed below::
51
52 $ head -n 13 m209keys.cfg
53 [AB]
54 lugs = 0-4*4 0-5*6 1-0*10 2-0*2 3-0 3-5*2 3-6 4-5
55 wheel1 = BDFGIKRSTUWX
56 wheel2 = BCEJKLORSUX
57 wheel3 = CFHJKLMQSTU
58 wheel4 = ABCDHIJMOPRTU
59 wheel5 = BCEFINPS
60 wheel6 = ACDEHJN
61 check = GZWUU SFYQN NFAKK FXSEN FAFMF B
62
63 [AK]
64 lugs = 0-4*2 0-5*9 0-6 1-0*3 1-2 1-5 1-6*2 3-0*8
65 wheel1 = ABDEFHIJMQSUXZ
66
67 .. NOTE::
68 If you are following along at home, you'll probably get different
69 output than what is shown here. This is because the key lists are generated
70 at random, and it is very unlikely that your key list matches mine!
71
72 Here we can see that the first key list in our file has the indicator ``AB``
73 (shown in square brackets), and we can see the settings for the lugs and six
74 wheels. The notation is explained later. Also included is a so-called check
75 string. Because there are so many settings, it is quite error-prone to set up
76 an M-209. This check string allows the operator to verify their work. After
77 configuring the M-209 with the given settings, the operator can set the six key
78 wheels to ``AAAAAA``, then encipher the letter ``A`` 26 times. If the message
79 that appears on the paper tape matches the check string, the operator knows the
80 machine is set up correctly for the day.
81
82 After the key list ``AB``, the key list ``AK`` starts, and so on for all 30 key
83 lists.
84
85 Now that we have created a key file, we can encrypt our first message. The
86 ``m209`` utility has many options to let you have fine control over the various
87 encryption parameters. These are explained in detail later. If you omit these
88 parameters they are simply chosen at random. Here is the simplest example of
89 encryping a message::
90
91 $ m209 encrypt -t "THE PIZZA HAS ARRIVED STOP NO SIGN OF ENEMY FORCES STOP"
92 IIPDU FHLMB LASGD KTLDO OSRMZ PWGEB HYMCB IKSPT IUEPF FUHEO NQTWI VTDPC GSPQX IIPDU FHLMB
93
94 What just happened here? Since we did not specify a key file, the default
95 ``m209keys.cfg`` was used. Since we did not specify a key list indicator, one
96 was chosen randomly from the key file. Other encryption parameters, explained
97 later, were also randomly chosen. Next, the message given on the command-line
98 was encrypted using the standard US Army procedure described in the references.
99 This resulted in the encrypted message, which is displayed in 5-letter groups.
100 Notice that the first and last 2 groups are identical. These are special
101 indicators that tell the receiver how to decrypt the message. In particular
102 note that the last 2 letters in the second and last groups are ``MB``. This is
103 the key list indicator and tells the receiver what key list was used. The
104 remaining groups in the middle make up the encrypted message.
105
106 Astute M-209 enthusiasts will note that our message included spaces. Actual
107 M-209 units only allow the input of the letters ``A`` through ``Z``. Whenever
108 a space was needed, the operator inserted the letter ``Z``. The ``m209``
109 utility automatically performs this substitution for convenience.
110
111 Let's suppose our message was then sent to our recipient, either by courier,
112 Morse code over radio, or in the modern age, email or even Twitter. In order
113 for our receiver to decrypt our message they must also have the identical key
114 list named ``MB``. We will assume for now that our key file, ``m209keys.cfg``
115 was sent to our receiver earlier in some secure manner. The receiver then
116 issues this command::
117
118 $ m209 decrypt -t "IIPDU FHLMB LASGD KTLDO OSRMZ PWGEB HYMCB IKSPT IUEPF FUHEO NQTWI VTDPC GSPQX IIPDU FHLMB"
119 THE PI A HAS ARRIVED STOP NO SIGN OF ENEMY FORCES STOP
120
121 Here again, since no key file was explicitly specified, the file
122 ``m209keys.cfg`` was used. The file was searched for the key list ``MB``. Then
123 the standard Army procedure was followed, making use of the indicator groups to
124 decrypt the message, which is displayed as output.
125
126 But wait, what happened to our Pizza? Why are the ``Z``'s missing? This is how
127 an actual M-209 operates. Recall that an operator must substitute a letter
128 ``Z`` whenever a space is needed. The M-209 helpfully replaces the letter ``Z``
129 in the decrypt output with a space as an aid to the operator. As a side effect,
130 legitimate uses of the letter ``Z`` are blanked out. But usually it is clear
131 from context what has happened, and the operator has to put them back into the
132 message before passing it up the chain of command.
133
134 It may also happen that the original message did not fit perfectly into an even
135 number of 5-letter groups. In that case the encrypted message would be padded
136 with ``X`` characters according to procedure. Upon decrypt, these ``X``
137 characters would appear as garbage characters on the end of the message. The
138 receiving operator would simply ignore these letters. Note that our message did
139 not exhibit this behavior.
140
141 This is all you need to know to start creating your own M-209 messages! For
142 more details, consult the command-line ``m209`` documentation.
143
144 Library Tutorial
145 ----------------
38 146
39 Requirements 147 Requirements
40 ------------ 148 ------------
41 149
42 ``m209`` is written in Python_, specifically Python 3.3. It has no other 150 ``m209`` is written in Python_, specifically Python 3.3. It has no other