Mercurial > public > m209

annotate docs/tutorial.rst @ 68:30aa114bb746

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added docs for StdProcedure and exceptions.
author Brian Neal <bgneal@gmail.com>
date Sun, 21 Jul 2013 14:03:55 -0500
parents 21627ec5b1ad
children 854c5d361011
rev   line source
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@56 14 a key file that hold 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@56 41 at random, and it is very unlikely that your key list matches 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@56 45 wheels. The notation is explained later. Also included is a so-called check
bgneal@56 46 string. Because there are so many settings, it is quite error-prone to set up
bgneal@56 47 an M-209. This check string allows the operator to verify their work. After
bgneal@56 48 configuring the M-209 with the given settings, the operator can set the six key
bgneal@56 49 wheels to ``AAAAAA``, then encipher the letter ``A`` 26 times. If the message
bgneal@56 50 that appears on the paper tape matches the check string, the operator knows the
bgneal@56 51 machine is set up correctly for the day.
bgneal@56 52
bgneal@56 53 After the key list ``AB``, the key list ``AK`` starts, and so on for all 30 key
bgneal@56 54 lists.
bgneal@56 55
bgneal@56 56 Now that we have created a key file, we can encrypt our first message. The
bgneal@56 57 ``m209`` utility has many options to let you have fine control over the various
bgneal@56 58 encryption parameters. These are explained in detail later. If you omit these
bgneal@56 59 parameters they are simply chosen at random. Here is the simplest example of
bgneal@56 60 encryping a message::
bgneal@56 61
bgneal@56 62 $ m209 encrypt -t "THE PIZZA HAS ARRIVED STOP NO SIGN OF ENEMY FORCES STOP"
bgneal@56 63 IIPDU FHLMB LASGD KTLDO OSRMZ PWGEB HYMCB IKSPT IUEPF FUHEO NQTWI VTDPC GSPQX IIPDU FHLMB
bgneal@56 64
bgneal@56 65 What just happened here? Since we did not specify a key file, the default
bgneal@56 66 ``m209keys.cfg`` was used. Since we did not specify a key list indicator, one
bgneal@56 67 was chosen randomly from the key file. Other encryption parameters, explained
bgneal@56 68 later, were also randomly chosen. Next, the message given on the command-line
bgneal@56 69 was encrypted using the standard US Army procedure described in the references.
bgneal@56 70 This resulted in the encrypted message, which is displayed in 5-letter groups.
bgneal@56 71 Notice that the first and last 2 groups are identical. These are special
bgneal@56 72 indicators that tell the receiver how to decrypt the message. In particular
bgneal@56 73 note that the last 2 letters in the second and last groups are ``MB``. This is
bgneal@56 74 the key list indicator and tells the receiver what key list was used. The
bgneal@56 75 remaining groups in the middle make up the encrypted message.
bgneal@56 76
bgneal@56 77 Astute M-209 enthusiasts will note that our message included spaces. Actual
bgneal@56 78 M-209 units only allow the input of the letters ``A`` through ``Z``. Whenever
bgneal@56 79 a space was needed, the operator inserted the letter ``Z``. The ``m209``
bgneal@56 80 utility automatically performs this substitution for convenience.
bgneal@56 81
bgneal@56 82 Let's suppose our message was then sent to our recipient, either by courier,
bgneal@56 83 Morse code over radio, or in the modern age, email or even Twitter. In order
bgneal@56 84 for our receiver to decrypt our message they must also have the identical key
bgneal@56 85 list named ``MB``. We will assume for now that our key file, ``m209keys.cfg``
bgneal@56 86 was sent to our receiver earlier in some secure manner. The receiver then
bgneal@56 87 issues this command::
bgneal@56 88
bgneal@56 89 $ m209 decrypt -t "IIPDU FHLMB LASGD KTLDO OSRMZ PWGEB HYMCB IKSPT IUEPF FUHEO NQTWI VTDPC GSPQX IIPDU FHLMB"
bgneal@56 90 THE PI A HAS ARRIVED STOP NO SIGN OF ENEMY FORCES STOP
bgneal@56 91
bgneal@56 92 Here again, since no key file was explicitly specified, the file
bgneal@56 93 ``m209keys.cfg`` was used. The file was searched for the key list ``MB``. Then
bgneal@56 94 the standard Army procedure was followed, making use of the indicator groups to
bgneal@56 95 decrypt the message, which is displayed as output.
bgneal@56 96
bgneal@56 97 But wait, what happened to our Pizza? Why are the ``Z``'s missing? This is how
bgneal@56 98 an actual M-209 operates. Recall that an operator must substitute a letter
bgneal@56 99 ``Z`` whenever a space is needed. The M-209 helpfully replaces the letter ``Z``
bgneal@56 100 in the decrypt output with a space as an aid to the operator. As a side effect,
bgneal@56 101 legitimate uses of the letter ``Z`` are blanked out. But usually it is clear
bgneal@56 102 from context what has happened, and the operator has to put them back into the
bgneal@56 103 message before passing it up the chain of command.
bgneal@56 104
bgneal@56 105 It may also happen that the original message did not fit perfectly into an even
bgneal@56 106 number of 5-letter groups. In that case the encrypted message would be padded
bgneal@56 107 with ``X`` characters according to procedure. Upon decrypt, these ``X``
bgneal@56 108 characters would appear as garbage characters on the end of the message. The
bgneal@56 109 receiving operator would simply ignore these letters. Note that our message did
bgneal@56 110 not exhibit this behavior.
bgneal@56 111
bgneal@56 112 This is all you need to know to start creating your own M-209 messages! For
bgneal@56 113 more details, consult the command-line ``m209`` documentation.
bgneal@56 114
bgneal@56 115 Library Tutorial
bgneal@56 116 ----------------
bgneal@56 117
bgneal@56 118 Here is one way to perform the encrypt and decrypt operations from the
bgneal@56 119 command-line tutorial, above. In order to produce the same output, we explicity
bgneal@56 120 specify the encryption parameters: the key list, the external message
bgneal@56 121 indicator, and the system indicator. These parameters are explained in the
bgneal@56 122 reference documentation.
bgneal@56 123
bgneal@56 124 .. literalinclude:: ../examples/encrypt.py
bgneal@56 125
bgneal@56 126 This program outputs::
bgneal@56 127
bgneal@56 128 IIPDU FHLMB LASGD KTLDO OSRMZ PWGEB HYMCB IKSPT IUEPF FUHEO NQTWI VTDPC GSPQX IIPDU FHLMB
bgneal@56 129
bgneal@56 130 A decrypt is just a bit more complicated. After constructing a ``StdProcedure``
bgneal@56 131 object, you hand it the encrypted message to analyze. The procedure object
bgneal@56 132 examines the groups in the message and extracts all the indicators. These are
bgneal@56 133 returned as a ``DecryptParams`` named tuple which indicates, amongst other
bgneal@56 134 things, what key list is required. It is then up to you to obtain this key list
bgneal@56 135 somehow. Here we use the ``read_key_list()`` function to do so. After
bgneal@56 136 installing the key list into the procedure object, you can finally call
bgneal@56 137 ``decrypt()``:
bgneal@56 138
bgneal@56 139 .. literalinclude:: ../examples/decrypt.py
bgneal@56 140
bgneal@56 141 This program prints::
bgneal@56 142
bgneal@56 143 THE PI A HAS ARRIVED STOP NO SIGN OF ENEMY FORCES STOP