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 Key list file format). 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 References (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 Command-line Reference.

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 References [5] & [7].

"""Example of how to perform an encrypt operation using the standard
procedure. Assumes a key file named m209keys.cfg exists in the current directory
and contains the key list with indicator MB.

"""
from m209.procedure import StdProcedure
from m209.keylist.config import read_key_list

key_list = read_key_list('m209keys.cfg', 'MB')
if key_list:
    proc = StdProcedure(key_list=key_list)
    plaintext = "THE PIZZA HAS ARRIVED STOP NO SIGN OF ENEMY FORCES STOP"
    msg = proc.encrypt(plaintext, spaces=True, ext_msg_ind='PDUFHL', sys_ind='I')
    print(msg)
else:
    print("Key list MB not found")

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 with set_key_list(), you can finally call decrypt():

"""Example of how to perform a decrypt operation using the standard
procedure. Assumes a key file named m209keys.cfg exists in the current directory
and contains the key list with indicator MB.

"""
from m209.procedure import StdProcedure
from m209.keylist.config import read_key_list

msg = ('IIPDU FHLMB LASGD KTLDO OSRMZ PWGEB HYMCB IKSPT IUEPF FUHEO NQTWI VTDPC'
      ' GSPQX IIPDU FHLMB')

proc = StdProcedure()
params = proc.set_decrypt_message(msg)
key_list = read_key_list('m209keys.cfg', params.key_list_ind)
if key_list:
    proc.set_key_list(key_list)
    plaintext = proc.decrypt()
    print(plaintext)
else:
    print("Key list '{}' not found".format(params.key_list_ind))

This program prints:

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