# HG changeset patch # User Brian Neal # Date 1373051932 18000 # Node ID 7fd3ec5580ab34256b44e10899d76e5c77cf2103 # Parent 41df1e5308e92afb356534ad5cd889c0038b234b More work on the docs. Added command-line tutorial. diff -r 41df1e5308e9 -r 7fd3ec5580ab docs/index.rst --- a/docs/index.rst Thu Jul 04 23:02:42 2013 -0500 +++ b/docs/index.rst Fri Jul 05 14:18:52 2013 -0500 @@ -30,11 +30,119 @@ command-line application that can encrypt & decrypt messages for scripting and experimentation. -Command-line Example --------------------- +Command-line Tutorial +--------------------- -Library Example ---------------- +In order for two parties to exchange M-209 messages, each must set up their +device in exactly the same manner. This was accomplished by publishing key +lists in code books which were distributed to end users. A code book instructed +users on what key list to use on any given day in a given month. Each key list +detailed the numerous wheel pin and lug settings that needed to be made for +a given day. Because there are so many settings, the ``m209`` utility allows +users to store key lists in a key file for convenience. So let us first create +a key file that hold 30 key lists:: + + $ m209 keygen -n 30 + +This command randomly creates 30 key lists and stores them in a file called +``m209keys.cfg`` by default. We did not specify a starting key list indicator, so +30 random ones were chosen. The first 13 lines of our new key file are +displayed below:: + + $ head -n 13 m209keys.cfg + [AB] + lugs = 0-4*4 0-5*6 1-0*10 2-0*2 3-0 3-5*2 3-6 4-5 + wheel1 = BDFGIKRSTUWX + wheel2 = BCEJKLORSUX + wheel3 = CFHJKLMQSTU + wheel4 = ABCDHIJMOPRTU + wheel5 = BCEFINPS + wheel6 = ACDEHJN + check = GZWUU SFYQN NFAKK FXSEN FAFMF B + + [AK] + lugs = 0-4*2 0-5*9 0-6 1-0*3 1-2 1-5 1-6*2 3-0*8 + wheel1 = ABDEFHIJMQSUXZ + +.. NOTE:: + If you are following along at home, you'll probably get different + output than what is shown here. This is because the key lists are generated + at random, and it is very unlikely that your key list matches mine! + +Here we can see that the first key list in our file has the indicator ``AB`` +(shown in square brackets), and we can see the settings for the lugs and six +wheels. The notation is explained later. Also included is a so-called check +string. Because there are so many settings, it is quite error-prone to set up +an M-209. This check string allows the operator to verify their work. After +configuring the M-209 with the given settings, the operator can set the six key +wheels to ``AAAAAA``, then encipher the letter ``A`` 26 times. If the message +that appears on the paper tape matches the check string, the operator knows the +machine is set up correctly for the day. + +After the key list ``AB``, the key list ``AK`` starts, and so on for all 30 key +lists. + +Now that we have created a key file, we can encrypt our first message. The +``m209`` utility has many options to let you have fine control over the various +encryption parameters. These are explained in detail later. If you omit these +parameters they are simply chosen at random. Here is the simplest example of +encryping a message:: + + $ m209 encrypt -t "THE PIZZA HAS ARRIVED STOP NO SIGN OF ENEMY FORCES STOP" + IIPDU FHLMB LASGD KTLDO OSRMZ PWGEB HYMCB IKSPT IUEPF FUHEO NQTWI VTDPC GSPQX IIPDU FHLMB + +What just happened here? Since we did not specify a key file, the default +``m209keys.cfg`` was used. Since we did not specify a key list indicator, one +was chosen randomly from the key file. Other encryption parameters, explained +later, were also randomly chosen. Next, the message given on the command-line +was encrypted using the standard US Army procedure described in the references. +This resulted in the encrypted message, which is displayed in 5-letter groups. +Notice that the first and last 2 groups are identical. These are special +indicators that tell the receiver how to decrypt the message. In particular +note that the last 2 letters in the second and last groups are ``MB``. This is +the key list indicator and tells the receiver what key list was used. The +remaining groups in the middle make up the encrypted message. + +Astute M-209 enthusiasts will note that our message included spaces. Actual +M-209 units only allow the input of the letters ``A`` through ``Z``. Whenever +a space was needed, the operator inserted the letter ``Z``. The ``m209`` +utility automatically performs this substitution for convenience. + +Let's suppose our message was then sent to our recipient, either by courier, +Morse code over radio, or in the modern age, email or even Twitter. In order +for our receiver to decrypt our message they must also have the identical key +list named ``MB``. We will assume for now that our key file, ``m209keys.cfg`` +was sent to our receiver earlier in some secure manner. The receiver then +issues this command:: + + $ m209 decrypt -t "IIPDU FHLMB LASGD KTLDO OSRMZ PWGEB HYMCB IKSPT IUEPF FUHEO NQTWI VTDPC GSPQX IIPDU FHLMB" + THE PI A HAS ARRIVED STOP NO SIGN OF ENEMY FORCES STOP + +Here again, since no key file was explicitly specified, the file +``m209keys.cfg`` was used. The file was searched for the key list ``MB``. Then +the standard Army procedure was followed, making use of the indicator groups to +decrypt the message, which is displayed as output. + +But wait, what happened to our Pizza? Why are the ``Z``'s missing? This is how +an actual M-209 operates. Recall that an operator must substitute a letter +``Z`` whenever a space is needed. The M-209 helpfully replaces the letter ``Z`` +in the decrypt output with a space as an aid to the operator. As a side effect, +legitimate uses of the letter ``Z`` are blanked out. But usually it is clear +from context what has happened, and the operator has to put them back into the +message before passing it up the chain of command. + +It may also happen that the original message did not fit perfectly into an even +number of 5-letter groups. In that case the encrypted message would be padded +with ``X`` characters according to procedure. Upon decrypt, these ``X`` +characters would appear as garbage characters on the end of the message. The +receiving operator would simply ignore these letters. Note that our message did +not exhibit this behavior. + +This is all you need to know to start creating your own M-209 messages! For +more details, consult the command-line ``m209`` documentation. + +Library Tutorial +---------------- Requirements ------------