Command-line Reference

Overview

The m209 command-line utility performs three functions:

• Creates key list files

• Encrypts text, either given on the command line or read from a file

• Decrypts text, either given on the command line or read from a file

These functions are implemented as sub-commands. To see the list of sub-commands and options common to all sub-commands, use the -h or --help option:

$ m209 --help
usage: m209 [-h] [-l {debug,info,warning,error,critical}]
            {encrypt,enc,decrypt,dec,keygen,key} ...

M-209 simulator and utility program

optional arguments:
  -h, --help            show this help message and exit
  -l {debug,info,warning,error,critical}, --log {debug,info,warning,error,critical}
                        set log level [default: warning]

list of commands:
  type m209 {command} -h for help on {command}

  {encrypt,enc,decrypt,dec,keygen,key}
    encrypt (enc)       encrypt text from file or command-line
    decrypt (dec)       decrypt text from file or command-line
    keygen (key)        generate key list

The -l / --log options control the verbosity of output. Currently only the keygen sub-command makes use of this option.

Each sub-command has an alias for those who prefer shorter commands.

Keygen sub-command

keygen, or key for short, is the sub-command that pseudo-randomly creates key list files for use by the encrypt and decrypt sub-commands, as well as by the m209 library routines.

Help on the keygen sub-command can be obtained with the following invocation:

$ m209 keygen --help
usage: m209 keygen [-h] [-z KEY_FILE] [-o] [-s XX] [-n NUMBER]

Generate key list file

optional arguments:
  -h, --help            show this help message and exit
  -z KEY_FILE, --key-file KEY_FILE
                        path to key list file [default: m209keys.cfg]
  -o, --overwrite       overwrite key list file if it exists
  -s XX, --start XX     starting indicator; if omitted, random indicators are
                        used
  -n NUMBER, --number NUMBER
                        number of key lists to generate [default: 1]

The options for keygen are described below.

-z or --key-file

This option names the key list file. If not supplied, this defaults to m209keys.cfg. Note that the other sub-commands also have this option, and they too use the same default value.

-o or --overwrite

This switch must be present if the key list file already exists. It provides confirmation that the user wants to overwrite an existing file. If the key list file already exists, and this option is not supplied, this sub-command will exit with an error message and the original key list file will be unchanged.

-s or --start

This option sets the starting indicator for the key list file. Key list indicators are two letters in the range AA to ZZ. For example, keygen can be told to create 3 key lists, starting with indicator AA. In this case the key lists AA, AB, and AC would be written to the file. If this parameter is omitted, keygen picks indicators at random. Key list indicators simply name the key list, and are placed in the leading and trailing groups of encrypted messages to tell the receiver which key list was used to create the message. Both sender and receiver must have the same key list (name and contents) to communicate.

-n or --number

This option specifies the number of key lists to generate. The default value is 1.

Note

The algorithm the keygen sub-command uses to generate key lists is based on the actual US Army procedure taken from the 1944 manual. This procedure is somewhat loosely specified and a lot is left up to the soldier creating the key list. The keygen algorithm is ad-hoc and uses simple heuristics and random numbers to make decisions. Occasionally this algorithm may fail to generate a key list that meets the final criteria defined in the manual. If this happens an error message will be displayed and no key list file will be created. It is suggested to simply run the command again as it is not likely to happen twice in a row.

Keygen examples

To generate 30 key lists in the default key list file (m209keys.cfg) with random indicators, and overwriting the key list file if it exists:

$ m209 keygen -o -n 30
$ m209 key --overwrite --number=30

To generate 5 key lists that sequentially start with the indicator BN in the key list file m209/keys/november/keys.cfg:

$ m209 keygen -z m209/keys/november/keys.cfg -s BN -n 5

Encrypt sub-command

encrypt, or enc, is the sub-command used to encrypt text. To get help on the encrypt command, type the following:

$ m209 encrypt -h
usage: m209 encrypt [-h] [-z KEY_FILE] [-f FILE] [-t TEXT] [-k XX] [-e ABCDEF]
                    [-s S]

Encrypt text from a file or command-line

optional arguments:
  -h, --help            show this help message and exit
  -z KEY_FILE, --key-file KEY_FILE
                        path to key list file [default: m209keys.cfg]
  -f FILE, --file FILE  path to plaintext file or - for stdin
  -t TEXT, --text TEXT  text string to encrypt
  -k XX, --key-list-ind XX
                        2-letter key list indicator; if omitted a random one
                        is used
  -e ABCDEF, --ext-ind ABCDEF
                        6-letter external message indicator; if omitted a
                        random one is used
  -s S, --sys-ind S     1-letter system indicator; if omitted a random one is
                        used

Either the -f/--file or -t/--text arguments must be supplied

The options to the encrypt command are described below.

-z or --key-file

This option names the key list file. If not given, the default of m209keys.cfg is used.

-f or --file

This option specifies the file that contains the text to encrypt. If the filename is given as - then input is read directly from stdin. Note that either this option or the -t option must be specified, but not both.

-t or --text

This option specifies the text to encrypt on the command-line. Depending upon your system, you’ll probably have to quote or escape your text. Note that you must either specify this option or the -f option, but not both.

-k or --key-list-ind

This option specifies the two-letter key list indicator to use. Valid values range from AA to ZZ. The key list with this indicator must be in the key list file given by the -z option. If this option is omitted, a key list from the key list file is chosen at random.

-e or --ext-ind

This option specifies the six-letter external message indicator, which is an encryption parameter as explained in the 1944 manual (see References [5] & [7]). Each letter must exist on the key wheels from left to right. If this option is omitted, an external message indicator is chosen at random.

-s or --sys-ind

This option specifies the one-letter system indicator, which is an encryption parameter as explained in the 1944 manual (see References [5] & [7]). This must be a letter from A to Z. If not given, one is chosen at random.

Note

An actual M-209 can only accept the letters A-Z. When using an actual M-209, space characters must be input as the letter Z. Numbers must typically be spelled out as words or some other agreed-upon convention. Likewise with punctuation. To make encryption more convenient, the m209 program will accept spaces and automatically convert them to the letter Z. Lowercase letters will automatically be converted to uppercase. All other characters will be silently dropped from the input. This applies to both text read on the command-line with the -t option and text read from files (-f).

Encrypt examples

To encrypt a simple string on the command-line using the default key file and random encryption parameters:

$ m209 encrypt -t "Rendezvous at zero seven thirty"
BBEPH SSLBY RKHWO OBAJB VYQEQ NJHGV FWRCJ UZHMB PXXXX BBEPH SSLBY

To save the encrypted text to a file:

$ m209 encrypt -t "Rendezvous at zero seven thirty" > secret.txt

To read the contents of a file and encrypt it, saving it to a new file:

$ m209 enc -f message.txt > secret.txt

To explicitly specify encryption parameters, and read text from stdin:

$ cat message.txt | m209 enc --file=- -k SU -e ZQGMFO -s A

Decrypt sub-command

decrypt, or dec, is the sub-command used to decrypt text. To get help on the decrypt command, type the following:

$ m209 decrypt --help
usage: m209 decrypt [-h] [-z KEY_FILE] [-f FILE] [-t TEXT]

Decrypt text from a file or command-line

optional arguments:
  -h, --help            show this help message and exit
  -z KEY_FILE, --key-file KEY_FILE
                        path to key list file [default: m209keys.cfg]
  -f FILE, --file FILE  path to ciphertext file or - for stdin
  -t TEXT, --text TEXT  text string to decrypt

Either the -f/--file or -t/--text arguments must be supplied

The options to the decrypt command are described below.

-z or --key-file

This option names the key list file. If not given, the default of m209keys.cfg is used.

-t or --file

This option specifies the file that contains the text to decrypt. If the filename is given as - then input is read directly from stdin. Note that either this option or the -t option must be specified, but not both.

-t or --text

This option specifies the text to decrypt on the command-line. Depending upon your system, you’ll probably have to quote or escape your text. Note that you must either specify this option or the -f option, but not both.

Note

The first and last 2 groups of an encrypted message contain the information needed to decrypt the message: the system indicator, the external message indicator, and the key list indicator. If the key list file given to the decrypt command does not contain the key list used to encrypt the message, then the message cannot be decrypted and an error message will be displayed.

Decrypt examples

To decrypt a simple string on the command-line using the default key file:

$ m209 decrypt -t "BBEPH SSLBY RKHWO OBAJB VYQEQ NJHGV FWRCJ UZHMB PXXXX BBEPH SSLBY"
RENDE VOUS AT  ERO SEVEN THIRTYXSJQ

To save the decrypted text to a file:

$ m209 decrypt -t "BBEPH SSLBY RKHWO OBAJB VYQEQ NJHGV FWRCJ UZHMB PXXXX BBEPH SSLBY" > msg.txt

To read the contents of a file and decrypt it, saving it to a new file:

$ m209 dec -f secret.txt > msg.txt

To decrypt from stdin:

$ cat secret.txt | m209 dec -f -
RENDE VOUS AT  ERO SEVEN THIRTYXSJQ

Note

In this example, the last group of the encrypted message only has one letter. It was padded out to five letters with X’s by the encryption process, and thus four “garbage” letters appear at the end in the decrypted output.

Note also that the Z in RENDEZVOUS and ZERO were converted to spaces by the decrypt process.

In both of these cases the operator would have to “fix up” the message before passing it up the chain of command.