Mercurial > public > m209

comparison docs/tutorial.rst @ 56:21627ec5b1ad

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