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 holds 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 will match 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. This notation is explained later (see :ref:`key-list-file-format-label`).
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
encrypting 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
:ref:`references-label` (see [5] and [7]). 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. Usually it is clear from
context what has happened, and the operator has to put the ``Z``'s 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 :doc:`commandline`.

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 explicitly
specify the encryption parameters: the key list, the external message
indicator, and the system indicator. These parameters are explained in
:ref:`references-label` [5] & [7].

.. 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 :class:`~m209.procedure.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
:func:`~m209.keylist.config.read_key_list` function to do so. After installing
the key list into the procedure object with :meth:`~.StdProcedure.set_key_list`,
you can finally call :meth:`~.StdProcedure.decrypt`:

.. literalinclude:: ../examples/decrypt.py

This program prints::

   THE PI  A HAS ARRIVED STOP NO SIGN OF ENEMY FORCES STOP