# HG changeset patch # User Brian Neal # Date 1373146067 18000 # Node ID 21627ec5b1adee661090a32a715c0743b2bd1673 # Parent 9341896b93f0b38c918f8fc4063ef80deb56e3f2 Restucture docs a bit. Create a separate tutorials document. diff -r 9341896b93f0 -r 21627ec5b1ad docs/index.rst --- a/docs/index.rst Fri Jul 05 19:32:45 2013 -0500 +++ b/docs/index.rst Sat Jul 06 16:27:47 2013 -0500 @@ -30,146 +30,14 @@ command-line application that can encrypt & decrypt messages for scripting and experimentation. -Command-line Tutorial ---------------------- +Documentation +------------- -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:: +Contents: - $ 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 ----------------- - -Here is one way to perform the encrypt and decrypt operations from the -command-line tutorial, above. In order to produce the same output, we explicity -specify the encryption parameters: the key list, the external message -indicator, and the system indicator. These parameters are explained in the -reference documentation. - -.. literalinclude:: ../examples/encrypt.py - -This program outputs:: - - IIPDU FHLMB LASGD KTLDO OSRMZ PWGEB HYMCB IKSPT IUEPF FUHEO NQTWI VTDPC GSPQX IIPDU FHLMB - -A decrypt is just a bit more complicated. After constructing a ``StdProcedure`` -object, you hand it the encrypted message to analyze. The procedure object -examines the groups in the message and extracts all the indicators. These are -returned as a ``DecryptParams`` named tuple which indicates, amongst other -things, what key list is required. It is then up to you to obtain this key list -somehow. Here we use the ``read_key_list()`` function to do so. After -installing the key list into the procedure object, you can finally call -``decrypt()``: - -.. literalinclude:: ../examples/decrypt.py - -This program prints:: - - THE PI A HAS ARRIVED STOP NO SIGN OF ENEMY FORCES STOP +.. toctree:: + tutorial + :maxdepth: 2 Requirements @@ -178,7 +46,6 @@ ``m209`` is written in Python_, specifically Python 3.3. It has no other requirements or dependencies. - Installation ------------ @@ -198,23 +65,12 @@ $ python setup.py install - Support & Source ---------------- All support takes place at the `m209 Bitbucket page`_. Please enter any feature requests or bugs into the `issue tracker`_. -Next Steps ----------- - -Contents: - -.. toctree:: - :maxdepth: 2 - - - Indices and tables ================== diff -r 9341896b93f0 -r 21627ec5b1ad docs/tutorial.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/tutorial.rst Sat Jul 06 16:27:47 2013 -0500 @@ -0,0 +1,143 @@ +Tutorials +========= + +Command-line Tutorial +--------------------- + +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 +---------------- + +Here is one way to perform the encrypt and decrypt operations from the +command-line tutorial, above. In order to produce the same output, we explicity +specify the encryption parameters: the key list, the external message +indicator, and the system indicator. These parameters are explained in the +reference documentation. + +.. literalinclude:: ../examples/encrypt.py + +This program outputs:: + + IIPDU FHLMB LASGD KTLDO OSRMZ PWGEB HYMCB IKSPT IUEPF FUHEO NQTWI VTDPC GSPQX IIPDU FHLMB + +A decrypt is just a bit more complicated. After constructing a ``StdProcedure`` +object, you hand it the encrypted message to analyze. The procedure object +examines the groups in the message and extracts all the indicators. These are +returned as a ``DecryptParams`` named tuple which indicates, amongst other +things, what key list is required. It is then up to you to obtain this key list +somehow. Here we use the ``read_key_list()`` function to do so. After +installing the key list into the procedure object, you can finally call +``decrypt()``: + +.. literalinclude:: ../examples/decrypt.py + +This program prints:: + + THE PI A HAS ARRIVED STOP NO SIGN OF ENEMY FORCES STOP