Mercurial > public > m209

annotate 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
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@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