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