Mercurial > public > m209

comparison docs/tutorial.rst @ 71:854c5d361011

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Documentation cleanup.
author Brian Neal <bgneal@gmail.com>
date Tue, 23 Jul 2013 20:18:05 -0500
parents 21627ec5b1ad
children
comparison
equal deleted inserted replaced
70:753974fc7619 71:854c5d361011
9 lists in code books which were distributed to end users. A code book instructed 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 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 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 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 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:: 14 a key file that holds 30 key lists::
15 15
16 $ m209 keygen -n 30 16 $ m209 keygen -n 30
17 17
18 This command randomly creates 30 key lists and stores them in a file called 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 19 ``m209keys.cfg`` by default. We did not specify a starting key list indicator, so
36 wheel1 = ABDEFHIJMQSUXZ 36 wheel1 = ABDEFHIJMQSUXZ
37 37
38 .. NOTE:: 38 .. NOTE::
39 If you are following along at home, you'll probably get different 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 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! 41 at random, and it is very unlikely that your key list will match mine!
42 42
43 Here we can see that the first key list in our file has the indicator ``AB`` 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 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 45 wheels. This notation is explained later (see :ref:`key-list-file-format-label`).
46 string. Because there are so many settings, it is quite error-prone to set up 46 Also included is a so-called check string. Because there are so many settings,
47 an M-209. This check string allows the operator to verify their work. After 47 it is quite error-prone to set up an M-209. This check string allows the
48 configuring the M-209 with the given settings, the operator can set the six key 48 operator to verify their work. After configuring the M-209 with the given
49 wheels to ``AAAAAA``, then encipher the letter ``A`` 26 times. If the message 49 settings, the operator can set the six key wheels to ``AAAAAA``, then encipher
50 that appears on the paper tape matches the check string, the operator knows the 50 the letter ``A`` 26 times. If the message that appears on the paper tape
51 machine is set up correctly for the day. 51 matches the check string, the operator knows the machine is set up correctly
52 for the day.
52 53
53 After the key list ``AB``, the key list ``AK`` starts, and so on for all 30 key 54 After the key list ``AB``, the key list ``AK`` starts, and so on for all 30 key
54 lists. 55 lists.
55 56
56 Now that we have created a key file, we can encrypt our first message. The 57 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 ``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 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 parameters they are simply chosen at random. Here is the simplest example of
60 encryping a message:: 61 encrypting a message::
61 62
62 $ m209 encrypt -t "THE PIZZA HAS ARRIVED STOP NO SIGN OF ENEMY FORCES STOP" 63 $ 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 IIPDU FHLMB LASGD KTLDO OSRMZ PWGEB HYMCB IKSPT IUEPF FUHEO NQTWI VTDPC GSPQX IIPDU FHLMB
64 65
65 What just happened here? Since we did not specify a key file, the default 66 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 ``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 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 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 was encrypted using the standard US Army procedure described in
70 This resulted in the encrypted message, which is displayed in 5-letter groups. 71 :ref:`references-label` (see [5] and [7]). This resulted in the encrypted
71 Notice that the first and last 2 groups are identical. These are special 72 message, which is displayed in 5-letter groups. Notice that the first and last
72 indicators that tell the receiver how to decrypt the message. In particular 73 2 groups are identical. These are special indicators that tell the receiver how
73 note that the last 2 letters in the second and last groups are ``MB``. This is 74 to decrypt the message. In particular note that the last 2 letters in the
74 the key list indicator and tells the receiver what key list was used. The 75 second and last groups are ``MB``. This is the key list indicator and tells
75 remaining groups in the middle make up the encrypted message. 76 the receiver what key list was used. The remaining groups in the middle make
77 up the encrypted message.
76 78
77 Astute M-209 enthusiasts will note that our message included spaces. Actual 79 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 80 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`` 81 a space was needed, the operator inserted the letter ``Z``. The ``m209``
80 utility automatically performs this substitution for convenience. 82 utility automatically performs this substitution for convenience.
96 98
97 But wait, what happened to our Pizza? Why are the ``Z``'s missing? This is how 99 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 100 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`` 101 ``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, 102 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 103 legitimate uses of the letter ``Z`` are blanked out. Usually it is clear from
102 from context what has happened, and the operator has to put them back into the 104 context what has happened, and the operator has to put the ``Z``'s back into
103 message before passing it up the chain of command. 105 the message before passing it up the chain of command.
104 106
105 It may also happen that the original message did not fit perfectly into an even 107 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 108 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`` 109 with ``X`` characters according to procedure. Upon decrypt, these ``X``
108 characters would appear as garbage characters on the end of the message. The 110 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 111 receiving operator would simply ignore these letters. Note that our message did
110 not exhibit this behavior. 112 not exhibit this behavior.
111 113
112 This is all you need to know to start creating your own M-209 messages! For 114 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. 115 more details, consult the :doc:`commandline`.
114 116
115 Library Tutorial 117 Library Tutorial
116 ---------------- 118 ----------------
117 119
118 Here is one way to perform the encrypt and decrypt operations from the 120 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 121 command-line tutorial, above. In order to produce the same output, we explicitly
120 specify the encryption parameters: the key list, the external message 122 specify the encryption parameters: the key list, the external message
121 indicator, and the system indicator. These parameters are explained in the 123 indicator, and the system indicator. These parameters are explained in
122 reference documentation. 124 :ref:`references-label` [5] & [7].
123 125
124 .. literalinclude:: ../examples/encrypt.py 126 .. literalinclude:: ../examples/encrypt.py
125 127
126 This program outputs:: 128 This program outputs::
127 129
128 IIPDU FHLMB LASGD KTLDO OSRMZ PWGEB HYMCB IKSPT IUEPF FUHEO NQTWI VTDPC GSPQX IIPDU FHLMB 130 IIPDU FHLMB LASGD KTLDO OSRMZ PWGEB HYMCB IKSPT IUEPF FUHEO NQTWI VTDPC GSPQX IIPDU FHLMB
129 131
130 A decrypt is just a bit more complicated. After constructing a ``StdProcedure`` 132 A decrypt is just a bit more complicated. After constructing
131 object, you hand it the encrypted message to analyze. The procedure object 133 a :class:`~m209.procedure.StdProcedure` object, you hand it the encrypted
132 examines the groups in the message and extracts all the indicators. These are 134 message to analyze. The procedure object examines the groups in the message and
133 returned as a ``DecryptParams`` named tuple which indicates, amongst other 135 extracts all the indicators. These are returned as a ``DecryptParams`` named
134 things, what key list is required. It is then up to you to obtain this key list 136 tuple which indicates, amongst other things, what key list is required. It is
135 somehow. Here we use the ``read_key_list()`` function to do so. After 137 then up to you to obtain this key list somehow. Here we use the
136 installing the key list into the procedure object, you can finally call 138 :func:`~m209.keylist.config.read_key_list` function to do so. After installing
137 ``decrypt()``: 139 the key list into the procedure object with :meth:`~.StdProcedure.set_key_list`,
140 you can finally call :meth:`~.StdProcedure.decrypt`:
138 141
139 .. literalinclude:: ../examples/decrypt.py 142 .. literalinclude:: ../examples/decrypt.py
140 143
141 This program prints:: 144 This program prints::
142 145